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Licensing Requirements for Software Developers 

^jple has a low-cost licensing program, which permits developers of software 
for the Lisa to incorporate ^pie-developed libraries and object code files 
into their products. Both in-house and external distribution require a license. 
Before distributing any products that incorporate Apple software, please 
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technical inf ormatioa 
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Customer Satisfaction 

If you discover physical defects In the manuals distributed with a Lisa 
product or In the media on which a software product is distributed, Apple will 
replace the documentation or media at no charge to you during the 90-day 
period after you purchased the product 

In addition, If Apple releases a corrective update to a software product during 
the 90-day period after you purchased the software, ^jpie will replace the 
applicable diskettes and documentation with the revised version at no charge 
to you during the six months after the date of purchase. 

In some countries the replacement period may be different; check with your 
authorized Lisa dealer. Return any item to be replaced with proof of 
purchase to Apple or to an authorized Lisa dealer. 

Limitation on Warranties and Liability 

All implied warranties concerning this manual and media, including implied 
warranties of merchantability and fitness for a particular purpose, are limited 
in duration to ninety (90) days from the date of original retail purchase of 
this product 

Even though Apple has tested the software described in this manual and 
reviewed its contents, neither Apple nor its software suppliers make any 
warranty or representation, either egress or implied, with respect to this 
manual or to the software described in this manual their quality, 
performance, merchantability, or fitness for any particular purpose. As a 
result, this software and manual are sold "as is," and you the purchaser are 
assuming the entire risk as to their quality and performance. 

In no event will Apple or its software suppliers be liable for direct, indirect, 
special, incidental or consequential damages resulting from any defect in the 
software or manual even if they have been advised of the possibility of such 
damages. In particular, they shall have no liability for any programs or data 
stored in or used with fipfie products, including the costs of recovering or 
reproducing these programs or data 

The warranty and remedies set forth above are exclusive and in lieu of all 
others, oral or written, express or implied. No /°pple dealer, agent or 
employee is authorized to make any modification extension or addition to this 
warranty. 

Some states do not allow the exclusion or limitation of implied warranties or 
liability for incidental or consequential damages, so the above limitation or 
exclusion may not apply to you. This warranty gives you specific legal rights, 
and you may also have other ri£tts that vary from state to state. 



License and Copyright 

This manual and the software (computer programs) described in it are copy- 
righted by Apple or by Apple's software suppliers, with all rights reserved 
and they are covered by the Lisa Software License Agreement signed by each 
Lisa owner, under the copyright laws and the License Agreement this 
manual or the programs may not be copied in whole or in part without the 
written consent of ^jple, except in the normal use of the software or to 
make a backup copy. This exception does not allow copies to be made for 
others, whether or not sold, but all of the material purchased (with all backup 
copies) may be sold given, or loaned to other persons if they agree to be 
bound by the provisions of the License Agreement Copying includes 
translating into another language or format 

You may use the software on any computer owned by you, but extra copies 
cannot be made for this purpose. For some products, a mulUuse license may 
be purchased to allow the software to be used on more than one computer 
owned by the purchaser, including a shared-disk system. (Contact your 
authorized Lisa dealer for more information on multiuse licenses.) 



PREFACE 



This manual documents the Lisa Applications ToolKit It is intended for 
experienced programmers. At a minimum, readers should be familiar with 
Lisa Pascal, Lisa Clascal, the Workshop, the Lisa User interface Guidelines 
and the Lisa office system. In particular, th? reader is assumed to be 
familiar with the meaning of the following terms: 

Clascal class class-type object object reference 

method pointer handle field tool 

window panel pane mouse mouse-pointer 

view control scrollbar scroll arrow resize icon elevator 

Chapter 1 describes the ToolKit in general. In particular it describes the 
different parts of the ToolKit, and the way those parts fit together. 

Chapter 2 describes UObJect That unit includes the basic definitions of 
objects and definitions of classes for the creation and manipulation of files 
and complex data structures. 

Chapter 3 describes UDraw, which defines classes used to convert displayed 
information from formats used by the ToolKit to formats used by QuickDraw, 
and vice versa 

Chapter 4 describes UABC, which implements most of the functions common 
to all Lisa applications. 

Chapter 5 describes the debugging facilities available with the ToolKit 

Chapter 6 documents reference information for ToolKit units, including global 
variables, procedures, and functions, and non-class type definitions. 

Part II contains reference sheets on all of the important ToolKit classes. 

The following typographic and linguistic conventions are observed in this 
manual: 

1. All program fragments, including variables and reserved words, are in bold 
type wherever they appear. Reserved words are, additionally, printed 
entirely with capital letters. 

2. All method, object, and class names are in bold type wherever they 
appear. This is to avoid confusion; for example, when the word "view" is 
shown in bold (view), it refers to an object called view. When "view" is 
used in a more casual context it is not bolded. An example is with 
"window," where there is the window as the box that appears on the 
cttsplay and the window as the instance of TWindow or instance of a 
descendant of TWindow that controls the window on the display. 

3. All class names begin with a capital T. The letter following the T is also 
capitalized. 
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4. Method names are always capitalized. 

5. Object-reference variable names and field names are not capitalized, even 
if they appear at the beginning of a sentence. (The one exception to this 
rule is in section titles, where object names are capitalized.) 

6. to\y words, or abbreviated words, appearing as parts of a class name, 
method name, or field name begin with a capital letter. For example, 
aUowMouseOutslde is a field name containing the words allow, mouse, and 
outside. 

7. When speaking of objects of some particular class, rather than of the class 
itself, the object is usually given the class name without the T. This is 
often used in a generic sense; for example, when speaking of 
characteristics of objects of class TProcess or of some descendent of 
TProcess, the object is called the process. 

8. The word document refers to the data associated with an icon on the 
desktop. 
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Introduction to the ToolKit 



Lisa applications are characterized by the following design principles: 

• Extensive use of graphics, including windows and the mouse pointer. 

• Use of pull-down menus for command s. 

• Few operating modes, or none at aflL 

• Data transfer between documents by simple cut and paste operations. 

The ToolKit is a set of libraries that, wherever possible, provide standard 
behavior that follows these principles. For example, all Lisa applications 
have windows that can be moved around the screen; usually the windows can 
be resized and scrolled. The ToolKit provides all of these functions. The 
ToolKit also displays a menu bar for the active application, and provides a 
number of standard menu functions, such as saving, printing, and setting aside. 

However, the ToolKit is more than a set of libraries. Because the ToolKit Is 
written using Clascal, the ToolKit is almost a complete program by itself. 
(See the introduction to Clascal ) you can, In fact write a five-line main 
program, compile It, link it with the ToolKit, and run it. What results Is the 
Generic Application. 

The Generic Application has many of the standard Lisa application 
characteristics. A piece of Generic application stationery can be torn off, 
and, when the new document is opened, it presents the user with a window 
with scroll bars, split controls, size control, and a title bar. The window can 
be moved, resized, and split into multiple panes. There Is a menu bar with a 
few standard functions, so that the generic document can be saved, printed, 
and set aside. The single Generic Application process can manage any 
number of documents, you cannot, however, do anything within the window, 
aside from creating panes. The space within the window, along with the 
additional menu functions, is the responsibility of the real application. 

Therefore, when you write a Lisa application using the ToolKit, you 
essentially write extensions to the Generic Application, it is easy to write 
extensions to any Clascal program. In order to create your application from 
the basic Generic Application, you create a set of subclasses, Including 
methods to perform the work of your application. You then write a simple 
main program and compile and link it with the ToolKit 

Whenever necessary, the ToolKit calls your application's routines, in 
particular, although the ToolKit draws the scroll bars and the rest of the 
frame of the window, your application must draw the contents of the window. 
For example, if the user scrolls the document, the ToolKit tells your program 
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to redraw the changed areas. The ToolKlt tells your program to redraw In 
other situations as well, such as when the user opens the window, chooses 
"Revert to Previous version" from the menu or enlarges the window. 

One advantage of Clascal Is that you can write applications in steps. You 
can begin by doing the least amount possible, and get an application that does 
very little, but will run. you can then extend your application bit by bit, 
checking as you go. This characteristic of Clascal makes it easy to extend 
the capabilities of ToolKlt programs, even years after you write the original 
program. 

Ll *me Parts of the TocflKlt 

The basic ToolKlt is contained in three units: 

• uooject defines class TObJect which is the ancestor class for ail Clascal 
objects. It Implements debugging, copying, and heap m anagement for all 
objects used in the ToolKlt It also implements a number of complex data 
structures. These data structures — arrays, strings, files, and lists — 
allow your program to easily store groups of data (This unit is also used 
when writing Clascal programs without the rest of the ToolKlt) 

• UDraw reimplements all QuickDraw procedures, using long Integers in 
place of QuickDraw's regular integers, so that documents can be as large 
as necessary. (Ordinary QuickDraw procedures used with the ToolKlt limit 
documents to 41 pages.) it also defines a number of graphics routines that 
are not defined by QuickDraw. 

• UABC contains the bulk of the TocflKlt the Application Base Classes. 

A set of other units, called building blocks, implement standard but not 
universal, behavior. These Include building blocks for text editing, creating 
rulers, and managing dialog boxes. 

LLl UObJect 

UObJect defines class TObJect All classes are d escenda n ts of TObJect 

UObJect implements the following characteristics for TObJect 

• Objects are stored on a compactabie heap. 

• Objects have certain debugging facilities available. 

• Objects can be freed; that is, have their heap space released. 

• Objects can be copied (clonecfc 

UObJect also implements a number of standard data structures for use with 
Clascal and the ToolKlt It implements a group of utility routines for use 
with the data structures. The data structures are 

• arrays, which are one-dimensional arrays of records. 

• lists, which are one-dimensional arrays of object-references. 
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• strings, which are one-dimensional strings of characters. 

• files, which are disk-based one-dimensional strings of characters. 

The utility methods provided for these classes allow your program to add, 
delete, and retrieve objects from the structures. 

In addition, UObject provides a set of utility classes that scan through the 
structures. 

The structures are all quite similar to each other. 

Any files created and handled by file objects are separate from the files used 
to store the application's documents. The document's files are created and 
managed entirely by the ToolKlt, and you generally never deal with them 
yourself. Every document has a docManager, an object of type TDocManager, 
which handles the document's files. 

Chapter 2 describes UObject more fully. 

LL2 UDraw 

QuickDraw is based on simple (16-bit) integers, and as a result, has fairly 
severe limitations on how large documents can be. The ToolKlt therefore 
provides unit UDraw, which defines drawing routines that use long (32-bit) 
integers, which can be used in place of QuickDraw routines that use simple 
integers. 

This change Increases the maximum document length and width from 41 pages 
in each dimension to something like four million pages in each dimension. 

UDraw also provides a small set of additional routines. These routines 
convert LRects (based on long Integers) to Rects (based on simple integers) 
and Rects to LRects, LPolnts to Points and Points to LPoints, in addition, 
there are routines that provide other useful functions. 

Chapter 3 describes UDraw more fully. 

1X3 UfiBC 

UABC, which defines the Application Base Classes, is the heart of the 
ToolKlt Most of the standard behavior provided by the ToolKlt is 
implemented in this unit It defines TPiocess, TDocManager, TWindow, 
TPenel TPane, TOommanct among other classes. The routines that handle the 
menus and the mouse are defined here. Most of the work you must do to get 
your application running involves subclassing UABC classes. 

For example, the class TDocManager contains methods to manage the files 
and data segments used by an application. You must always subclass 
TDocManager, so that your own files, rather than the generic files, are 
managed. 

Chapter 4 describes UABC more fully. 
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\AA Building Blocks 

The building blocks are units that provide useful behavior beyond what the 
basic ToolKlt does. The most commonly used building blocks are UText the 
Text Building Block, which provides simple text editing and formatting 
functions, and UDialog, which provides for program dialogs with the user. 

Another building block implements universal text for clipboard communication 
with non-ToolKit programs. 

This document does not discuss the building blocks. Sample programs using 
the existing building blocks, as well as some documentation, are available. 

Because building blocks are units that are added to programs on top of the 
existing ToolKlt units, any developer can create them, useful building blocks 
micpt implement graphics editing, bitmap editing, data entry and formatting, 
or table editing. 

L2 "me Parts of a ToojKlt ^plication 

One of the characteristics of Clascal is that programs should always deal 
with objects. Almost everything in an application is represented by an object, 
from the data to the scroll bars. For example, the window you see on the 
display is controlled by an instance of the ToolKlt class TWlndow. In this 
manual, the window object Is usually called window. 

A number of the objects your program will use are members of classes 
defined by the ToolKlt The most important ToolKlt classes for the 
p r o gra mmer are 

• TWlndow 

• Tvlew 
•TPanel 

• TSelectlon 

• TDocManager 

• TCommand 

There are also a number you never need to worry about For example, the 
scroll bars are defined by ToolKlt classes, but the ToolKlt handles them, in 
addition, the panes are controlled by instances of classes defined by the 
ToolKlt but the p rogra m mer does not have to deal directly with them. 

The objects that control the application's display are associated with the 
parts of the display that they control in Figure l-l. 

L2.1 me window 

A window object controls the region of the Lisa's display that belongs to one 
window of a particular application, me image produced on the Lisa display 
by the window objects is called a window. Windows have title bars, borders, 
and resize icons. (The scroll bars belong to the panel object See Subsection 
123.) 
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A sample window is shown in the bottom of Figure l-l. Notice that the 
window surrounds the panels and panes, but the panels and panes are 
controlled by separate objects. 

Your application can manage several documents at a time, each in its own 
window. At most one window and its associated window object is bound to 
the address space of the process at a time. 

Your application does not need to do much to make each window function 
correctly. Almost all window functions are handled by the ToolKit 

LZ2 The View 

The view object creates a graphical representation of the data used in an 
application. That graphical representation, the view's picture, is called the 
view. 

What you see in an application's window is usually Just a part of a view. If 
you scroll the window, you are essentially moving the window around on top 
of the view. Figure 1-1 shows how two noncontiguous pieces of the view are 
shown in the window. The shaded area of the view shown in the figure does 
not appear in either of the panes, and hence does not appear in the window. 
The user uses the scroll icons to show desired parts of the view. 

A window can have more than one view object. TTiere can be several views 
of a single set of data A LlsaGrapn window, which shows a numerical and a 
graphical representation of the same set of data, has two views and one data 
set in other applications, separate views may display independent sets of 
data. 

The application does not need to be concerned with what part of the view is 
actually shown in the window. The ToolKit can handle that Your application 
can, however, find out exactly what is visible in the window, to improve 
program efficiency. 

A view is created separately from the display. In order to show a view in a 
window, you associate the view object with a panel object 

123 The Panel 

The panel object controls the scroll icons and shows a portion of the view. 
Every view that is displayed is shown in a paneL 

Some applications, such as tisaWrite, have only one panel per window. 
Others, such as LisaGraph, have more than one. 
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Among Schoolchildren 
•:•;•:• by irf.B. Yeats;":-: 



I walk through the long schoolroom questioning ; x * 

A kind old nun in white hood replies; 

The children learn to cipher and to sing, 

To study reading books and history, 

To cut and sew, be neat in everything 

in the best modern way — the children's eyes 



In momentary yonder stare upon 
A sixty year old, smiling, public man 



•I dreamed of a Ledean body, bent 
Above; -a • sinking- fire-,; -a- tele- that- she 



.Told .of A .harsh - .reproof',, "or. trivial, "event, 



That changed some childish- dav to tragedy— 



Told, and it seemed that our two natures blent 

Into a sphere from youthful sympathy, 

Or else, to alter Plato's parable, 

into the yolk and white of the one shell. 




view 



selected 
object 



window 



and single 
panel 



I walfEM ^ the long schoolroom questioning ; 
A kind old nun in white hood replies; 
The children learn to cipher and to sing, 
To study reading books and history, 
To cut and sew , be neat ii^teverything 

in the best modern way — the chilcJbeoJs eyes 



Told, and it seemed that our two natures blent 

Into a sphere from youthful sympathy, 

Or else, to alter Plato's parable, 

into the yolk and white of the one shell. 



Note that there 
are two panes, 
but still only one 
panel. 




anes 



Figure 1-1 Window, Panel, Panes, and View 
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Each panel usually looks at a different view from every other panel. 

Figure l-i shows a one-panel window. Notice that the panel's vertical scroll 
bar is divided into two parts, one for each pane. Every panel object is 
associated with a single view object, so any panes in the panel can only show 
portions of that particular view, in Figure l-l* both of the panes show 
portions of the single view represented in the top of the figure. 

UZA The Pad 

The ToolKlt's graphics are computed using long integers. QuickDraw actually 
does the on-screen drawing using regular integers, pad objects are used to 
convert from long integers to regular Integers, and the other way around. 

Just as QuickDraw provides a global variable thePort, the ToolKit provides a 
global variable thePad to represent the current destination of graphic output 
The value of thePad changes as the destination of output changes, but those 
changes generally are transparent to your program. 

Programs often call the IPanel method OnADPadsDo, which assures that any 
changes made to a panel's display are shown in all parts of the paneL 

Programs also occasionally call methods of thePad. 

pane objects are members of class TPad, because TPane is a subclass of 
TPad. The effect of this is that any pane can be thePad and so, any pane 
can be the destination for graphic output 

123 The Selection 

Often, a command operates on an object that is currently selected. For 
example, in order to change the type style in Lisawrite, you select some 
characters and then choose a menu item. 

Every panel object has a selection object associated with it When a menu 
command is chosen, a com ma n d number is sent to the selection object, which 
then decides whether or not the comman d can be done, if it is possible to 
do, the selection object performs the operation, creates a comman d object 
that performs the operation, or tells another object to perform the operation. 

Every panel object has one and only one selection object If there is more 
than one panel in a given window, one of the panel objects is defined to be 
the selectPanel for the window object The selection In the setectPanel is 
given the application's command s . 

Any selection object can point to any number of display and/dr data objects, 
from zero on up. Those objects are the selected objects, Selected objects 
generally are highlighted in some way to draw attention to them. Figure l-l 
shows a single selected object in the window In the lower part of the figure. 
The selected object is highlighted by reverse video. 

L2j6 The Menu and Command s 

All commands available to an application user appear in pull-down menus that 
are listed in the menu bar. You create these menus by putting the menu 
names and item names in the phrase file for the application. Whenever the 
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user pulls down a menu, the application can enable or disable menu Items, and 
it can also mark menu items as checked off. If an Apple-key equivalent to a 
menu command is allowed, that is also in the phrase file. 

When a menu command is chosen, the command is given to the selection 
object in the selectPanel of the active window. 

If the command is not one of the application's commands, it is passed to the 
ToolKit, which carries out the command if it Is a legal ToolKit command, or 
notifies the user that the command cannot be dona 

13 Objects, Classes, and Space Allocation 

Every ToolKit class is a de s c e nda n t of class TObJect See the section on 
UObject (the unit that defines TObJect) for more information 

Pieces of data used in ToolKit applications are often stored in instances of 
classes, and so, are themselves objects* Data might be stored in objects of 
class types defined in the application or in the collection classes defined in 
UObject it Is important to store your program's information in objects, 
rather than in global variables, because only objects are saved and restored 
by the ToolKit If you do not store your information in objects, you must 
make certain that the information is saved and restored correctly. 

Class-type variables and other object references are not class objects, but 
actually are handles (double-indirect pointers) on objects. Note that it is 
not necessary (or even permissible) to use pointer variables or carets ( M ") to 
resolve these handles; when fields of the class are used, the variables are 
automatically resolved to return the stored values. 

Figure 1-2 shows how object references in programs are handles on objects 
stored in the document heap. 
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I Program Fragment!; 



TMyObject - SUBCLASS OF TObject; 
fieldl: INTEGER; 
field2: STRING [1..2] OF CHAR; 
FUNCTION CREATE: TMyObject; 



END; 
MyObject : TMyObject; 
BEGIN 
Myobject := TMyObject . CREATE ; 

MyODjeCt.TieJ.Qi. '.^ 7 J mnwnwrnimwim aMti 



VAR MyObject 



master pointer for object 


























'.'.'. . .". •« "iwtr • ■ • ' 


'.'.'.'.' ~.~.~.~.~.~.~.~HWBSrjiLW' "-'- 









Figure 1-2 Object References 
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Every subclass must have a CREATE method written specifically for that 
particular subclass. When a class's CREATE method Is used, a new Instance 
of the class (an object) Is created. That Is, CREATE allocates heap storage 
for the data stored In the object, and for pointers to the methods of the 
class. CREATE is a function that returns a handle on the new class object 

When a class-type variable's value is assigned to another class-type variable, 
the target class-type variable and the source, variable both point to the same 
object Here is an example, where red and green end up pointing at the same 
object 

TYPE 
TColor - SUBCLASS OF TObjBct [Defines a new class.} 
FUNCTION CREATE (object- TObJect ItsHeap: THeapfcTOolor; 
END; 
VAR 
green : TColor; {Creates a TCoiar-reference variable.} 
red : TColor; (Creates another TCoiar-reference variable! 
BEGIN 

greenHTCX^CREATEtobjectheap); (creates an Instance of TColor J 
red :- green; Intakes red point to the same object as green) 



Notice that there is never a CREATE call for the variable red The CREATE 
method allocates heap space for the object In the example above, the heap 
space is allocated by using CREATE to initialize the variable green When the 
value of green is assigned to red red becomes a handle on the same heap 
space on which green is a handle. CREATE methods create new storage 
space; a direct assignment to a class-type variable creates a new access path 
to the same storage space. 

Suppose you used a sequence like this: 

green y TCotor.CREATE (object* heapfc (Creates an instance of 

TCoksrJ 
red .- TCotorCREATE (object, heap); (Creates another instance 

of TColor.} 
red :■ green; Intakes red point to the same object as green} 

The storage space created when you used TCotorCREATE for red would be 
lost because red becomes a handle on the storage space created for green 
(The storage space created for red may be permanently lost to the program's 
use, because the heap manager maintains the space until it is deallocated 
with a Free method. TObJect has a Free method, and therefore, ail 
descendants of TObJect also have one. If you wanted to get rid of the object 
pointed to by red you would have used the method call re&Free before the 
line red ?- green) 
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Figure 1-3 represents the way different assignments work in a number of 
different cases. 



red : TColor; 



green : TColor; 




#■■■ 



red :- TColor.CREATE (heap); 



natter pointer 



TColor 

OOjOCt 



green :- red; 




green := TColor.CREATE (heap); 





Miter pointer 


H* 


TColor 
objoct, 


Mrtar pointer 


TColor 
objoot 



Figure 1-3 Class-type Variable Assignments 



When the variables green and red are first defined, they do not point 
anywhere. After TOolor.CREATE is used to create an object for red red 
points to a master pointer, which points to the new object Green still points 
nowhere. Assigning the value of red to green makes green point at the same 
master pointer, hence the same object as red. When TOoior.CREATE is 
called again to create a new object for green green points to the master 
pointer for the new object 

Notice the crucial difference between a class-type variable and an ordinary 
Pascal variable, such as a RECORD. A class-type variable is actually a 
handle on a piece of storage. Therefore, when the value of one class-type 
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variable is assigned to another, the second variable and the first point to the 
same piece of storage. When the value of a RECORD 1$ assigned to another 
RECORD, the second RECORD contains a duplicate of the first 

LA How the Parts Fit Together 

In an object-oriented program, the objects act on themselves when some 
object tells them to act In the ToolKit, the ultimate controlling object is 
the process. 

The process object contains a method called Run, Run consists of an event 
loop that checks the display, updates It when necessary, and checks for a 
command or other event When a command is received, the comman d is sent 
to the active selection object 

The event loop repeatedly checks for user events: key strokes, menu 
command s, and mouse clicks. When an event is received, an action Is taken 
depending on what type of event it is and where it happens. 

For example, when the mouse button is pressed the Window Manager, the part 
of the Lisa office system that manages the display, first checks to see if the ■ 
mouse was on the desktop, in one of the application windows, in the title bar 
for a window, or in the menu bar. If the mouse was within the outer 
boundary of an application's window (exclusive of the title bar), the window 
Manager gives the event to the process object for that application The 
process gives the event to the window object The window checks to see if 
the mouse was clicked on the resize icon. If so, the window tracks the 
mouse's movement until the button is released, and grows or shrinks the 
displayed window appropriately. If the mouse was not on the resize icon 
when the button was pressed the event is passed to the panel objects for the 
application Each of the panels checks to see if the event was within its 
outer boundaries. When one of the panels discovers that the area in which 
the mouse was clicked is within its boundaries, that panel tells its scroilBar 
objects to see if the mouse was there. If it was in a scroll bar, the panel 
scrolls appropriately. If the event was not in a scroll bar, the panel tests 
whether the event was In a panel resize Icon If it was in such an icon it 
resizes appropriately. Otherwise, the panel asks each of the pane objects, 
which control the visible contents of the panel to check if the event was 
within the area displayed by that pane. When one of the panes claims the 
mouse click, it informs the view object that controls the objects displayed by 
the pane. The view determines on which part of the view the mouse was 
clicked and then takes some action usually beginning a new selection Then 
the panel is given control again The panel tracks the movement of the 
mouse, informing the pane, view, and selection as the mouse moves. 

As another example, the mouse may have been clicked in the menu bar. In 
that case, the Window Manager gives the event to the process, which passes 
it to the window, which gives it to the mantfiar object The menuBar waits 
until a command is selected and then calls wlndowJDoOommand and sends it 
the command number. The window object calls selectlonCreateCommand 
which creates a uo i iiummJ object of the right type for that co mm a nd. The 
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c o mmand object is then told to carry out the command It may call ABC 
methods, building block methods, or application specific methods. 

Many of the higher level objects, such as the window and the selection, have 
fields that point to other objects. TWindow defines a field, 
TWindow-selectPanet which contains a handle on the setectPaneL Because all 
handles are equivalent object-references, and all references to objects are 
through handles, the window object can easiiy»call a method of the 
seiectPanel object in turn, the selectPanel has fields for any objects it 
needs to reach. 

The way you structure these field references is centra to rw your program 
operates. 

As a result of the fact that you often reach methods through fields, the calls 
to methods in ToolKit programs may occasionally seem quite complex. 

When myObJect is an object with the following definition: 

TYPE 
TMyObJect - SUBCLASS OF TObjBct {Creates a new class.} 

qualities: TQuark; (Defines a field of class TMyObJect) 

FUNCTION CREATE(obJect:TObjBCt; ltsHBapfTHeep): TMyObJect; 

END; 
V/W 

rnyobject TMyObJect; (Defines a TMyObJect-reference variable.) 

and TQuark and quark have this definition: 

TYPE 

TQuark - SUBCLASS OF TUsf (Creates a new classj 
FUNCTION CREATE (ObjBCtiTObjBCt; 

itsHeap:THeapirttlalSizeJNTEGER):TQufflK; 

FUNCTION ChangeSpin 0: WTEQERk 
END; 

quark: TQuark; pefines a TQuark-reference variablej 

you can invoke method TQuartcChangeSpin like this: 

quark :- TQuaricCREATE (object ItaHeap, kHUarSize}; (Creates an 

instance of 

TQUBtit} 

myObJect .- TMyObJectCREATE (object itsHaap); (Creates an instance 

of TMyObJect) 
myODjectqjallUes :- quark; flakes the qualities field of myODtect 

point to the same object as quartc} 
myObJectquaUUesiShengeSpin CDc (Mils a method of TQuark through 

the qualities field of myObJect} 

The effect of the last line is to change the spin in the ith element of the list 
object for which both myObJectquallUes and quaik are handles. There is only 
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one object although It is shown here with two separate handles. The 
following line has the same effect: 

quaricChangeSpin (ft 

15 Failure Donations 

Some ToolKlt methods and procedures return error codes when there is a 
failure, but many do not For example, if NewObJect (a global procedure 
defined in UObJect) fails to allocate because*the swapping space on the disk 
is full it does not return an error code. Instead when there is a failure, 
UObject's procedure ABCBieak is called. In the debugging version of the 
ToolKlt the Lisa beeps, and enters the debugger. Press the right-option key 
and the Enter key at the same time to display the alternate screen, which 
shows the error message. In the production version of the ToolKlt the 
Technical Difficulties alert Is displayed. The application terminates when the 
user responds to that alert 

To facilitate debugging, some error checks are enabled by command s In the 
Debug Menu, notably "Check List Indices," which enables subscript bounds 
checking In lists. 
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UObject 

21 ttWJt UObject 

UObject provides the basic structures for objects, object debugging, and object 
organization, sections 22 and 2.3 deal with the structure and concepts 
underlying these units. 

The type definitions provided by UObject provide capabilities In two 
categories: 

• Heap and memory management and debugging. This includes the definition 
of type TObJect which is the ancestor of all classes. TObJect and heap 
management are discussed In Section 22. TDe ToolKit debugger is 
discussed in Chapter 5. 

• Organization, inspection, and manipulation of groups of objects and other 
data. The collections provided allow for the creation and manipulation of 
lists, strings, arrays, and files. These are discussed in Section 2.3. 

22 Objects and Heaps 

UObject implements the most important and basic parts of the ToolKit namely 
heap management and the basic object definitions. The most basic object 
definition, that for TObJect is discussed in subsection 222. ToolKit heap 
m a nagement is discussed in Section 2.2.L 

22A How UObject Manages a Heap 

A heap consists of a header, an area for allocation of master pointers to 
objects, and a variable length storage area in which frequent allocation and 
deallocation occur. 

The value of any class-type variable is a double-incttrect pointer, a 4-byte 
handle on a 4-byte master pointer to an object consisting of a storage block 
(containing the fields of the object) and an 8-byte header comprised of: 

• A 2-byte indicator of the size of the object 

• A 2-byte locator for the master pointer. 

• A 4-byte indicator of the object's class. 

The master pointer and header together produce a 12-byte overhead for each 
object 

Objects are relocatable. When a heap fills up, it is compacted and the master 
pointers are updated. The master pointers are never moved. B ec a us e 
object-references are pointers to the master pointers, they do not have to be 
changed. If compacting the data on the heap does not yield enough space, the 
heap Is expanded. 

222 Creating Objects 

Every class must have its own, unique CREATE function. When you want to 
create a new object of some class, invoke the CREATE function for that class 
by calling TTnisClassJDREATE, where TThisClass is the name of the class. 
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The CREATE Auction allocates space on the heap fdr a new object of that 
class-type, and returns a handle on the new object Each subclass Is required 
by Clascal to define Its own CREATE function; CREATE is not a method, and 
is not overridden by the subclass, because the CREATE function fbr each 
subclass often has different arguments. 

Every CREATE function should, by convention, have a TObJect-type reference 
as its first parameter, and a heap as its secortf parameter. The remainder of 
the parameters depend on what you need to initialize the class. In general, 
CREATE functions follow the following model, where TMyObJect is the class 
you are defining, and TMyObJect is a subclass of TSuperObJect 

FUNCTION TMyObJectCREATE (ob£ TObJect; heap: THeep; 

parameters needed far this 
abject 
BEGN 

IF obJ-NIL THEN ob>- NewObJectyieap, THBCLASSfc 
SELF:- TMyObJect (TS0erObJectX)REAT€(obi reap, parameters 

needed by TSuperOb/ecfc 
(If TMyObjBCt is a subclass of TObJect the previous line 
is: SELF?- TMyObJect(obfiJ 
initialize myObJecfs parameters here) 
END; 

When you create a new object of type TMyObJect pass in ND. as the value of 
obj. The CREATE function sets the class pointer to TMyObJect and then calls 
each succeeding superclass, until TObJect is reached. TObJect allocates the 
proper amount of heap space, and then each subclass in turn initializes its 
fields. 

Note that because the class pointer is set at the beginning (by NewObJect), all 
SELF method calls in any CREATE function in the superclass chain call 
methods of TMyObJect If any of the superclasses^ CREATE functions call a 
method through SELF and the method is overridden by TMyObjBCt or by some 
other descendant of the calling class that is an ancestor of TMyObJect and 
that method e>qpects to have fields initialized in the object, you should 
initialize the fields before initializing SELF. You can Initialize those fields 
between the call to NewObJect and the call to TSuperObjBctCREATE. 

223 TODjBCt 

All class types are descenda n ts of the basic type TObJect defined in UObJect 
TObJect is the only class that has no superclass. It has no data fields, but it 
provides the basic methods used by all other classes. 

Any descendant of TObJect 

• inherits all methods and fields of its superclass. 

• can define methods Itself. 

• Can override any of its superclass's methods. 
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A subclass cannot however, change the interface definition for methods 
inherited from its superclass. *me single exception for this is for CREATE 
methods, the methods that create new objects of a given class-type. Every 
class defines its own interface to CREATE, as well as implementing the 
method. (A few methods listed in the ToolKlt Interface units are defined as 
conceptual methods. These methods, vrttlch are commented out of the 
interface, are listed only for information, and are not implemented or defined, 
subclasses can therefore define the interface for CONCEPTUAL methods in 
any way.) 

The following is a brief discussion of the most important methods of TObJect 
See the reference sheet for TObJect in Part II of this manual for more 
complete information. 



Returns the heap on which this object.is allocated. This method is never 
overridden. 

FreeObJect 

Deallocates the heap space taken by the object The master pointer and 
all references for the object are invalid after this method is executed 
Note that this method is rarely called (flrectly. You usually call Free. 
FreeObJect is almost never overridden. 

Free 

Free calls the Free method for every object referred to in the fields of 
the original object Free then calls FreeObJect to deallocate the space 
used by the original object TObtectFree simply calls FreeObJect because 
TObJect defines no fields. Tooirat classes override Free so that it frees 
all the objects referred to by fields defined by that subclass. When you 
create a new subclass and add fields to it you override Free so that it 
frees the objects in the fields you have added. You end by calling 
SUPERCLASSPrea Eventually, this chain of superclass calls reaches 
TObJecLFree, which calls TObJectFreeObjBct and frees your object The 
following example assumes that head and tail are fields of class TPair, 
and are object-re f e r en c e s . 

PROCEDURE TPairPree; 
BEGBN 

SELFJieadLFree; 

SELF.taiLFree; 

SUPERSELFPree; 
END; 

CloneObJect 

Creates a copy of the object and returns a handle on the new object 
This method is almost never overridden. 
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• Clone 

Creates a copy of the object and all its fields and returns a handle on the 
new object Similar to CioneObJect but Clone also creates copies of 
objects referred to by fields of the original object As with Free, you 
must re-implement Clone in your subclasses so that it copies 
field-referenced objects; TObJectClone simply calls CloneObJect See the 
description of Free for more information. 

• Debug 

Prints details about the object such as its class and the contents of its 
fields, on the alternate screen. It only exists in the debugging version of 
the ToolKit This method may be overridden but it seldom needs to be. 

• Fields 

Enumerates the contents of the fields of the objects. This is called by 
Debug. Because TObJect has no fields, TObJect>ields does nothing. You 
must implement Fields if you add fields to a subclass you create. The 
ToolKit Implements Fields for all ToolKit classes. You simply write a 
routine that calls SUPERSELF-Flelds and then enumerates the information 
for the fields you have added Fields methods only exist in the debugging 
version of the ToolKit You should compile your units fttFC fDbg OH). If 
you want to put your debugging code in a separate segment from the rest 
of your program, you can use is. see the reference sheet for TObJect in 
Part II of this manual for instructions for writing a Field method. You 
should follow those instructions so that the information appears in the 
correct format 

Here is a model for a Fields method. 

PROCEDURE TMyClassJFIeldsfpROCEDURE FtekframeAndType: 

S2551; 

BEGDM {The fields must be listed in declared order, with none 

omitted and none added.} 

{Call the superclass's Fields method first (unnecessary if the 

superclass is TObJect)) 

SUPERSELF.Flekft(Ftekfc 

Trte followi ng ty pe names are recognized by the parser. 

Ftek£flaj£BOOLEAtffc 

FteSSlnputOiar: CHARlt 
tvlTEQBRTt 
LONGJNTfc 
LPoJntt 
LRecfk 
Ftelofsize: Poinffc 
FieWCptr. Ptr^ 
FleldCtxiundRect: Recffc 
FieMTsane N anc: STRlNG[lOuT)c 
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FtekTsomeByte: HexBytet 

FleUCsomelnt: Hexlnteger* 

FleldCsomeNunnten Real* 

If the last field Is a Byte or a BOOUErti force padding to a word 

boundary by Inserting: 

near)? 

For safety, you can put that In every Fields method, it can 

appear anywhere In the listing. • - 

Every class name Is recognized. For example: 

FieldTmlscOt)> TODjectl; 

FieldfmyPanek wmfy 

Fieidfmysei: TMyseiectlonl; 

FteldCappSpeclflc: TAppSpeclflcl; 

You may report more than one field in a single call to reduce 

code space. 

FieUft»tmJtoctlJtoct£lzetf>oln^ 

Unpacked invariant RECORDS are recognized. 

Fieldflnfa RECORD version: NTEGER; size: Point END"* 

If the record has variants, use a CASE statement to choose 

between them. 

CASE SELF.vartant OF 
flavorl: FtekfRECORD version: INTEGER; size: Point END* 
flavors FleWCRECORD vtewLPt LPoint ENS* 

EhD; 

If SELF.vartant does not exist, choose one of the variant fields. 

unpacked ARRAYS with literal bounds are recognized. 

FieldTdesc: /^RAY [1^99] OF RECORD verston: lsTTEQER; kt 

/VRRAY [1-2J OF CHfiR END* 

Other constructs and type names are NOT recognized; substitute 

one of the above forms. 

as a last resort, use array [l^SCEOF(SELF.fiadName]g of Byte. 

END; 

23 Collections 

UObJect Imp lements the se basic organizational collections, all of which are 
objects, and descendants of type TCollecttan: 

• lists are indexed lists of object-reference s . 

• airays are one-dimensional lists of records. 

• strings are one-dimensional lists of characters. . 

• files are one-dimensional lists of characters stored in disk files. 

Notice that lists are made up of object-references. The objects themselves, 
like all objects, are stored separately on the heap, arrays and strings store 
their data within themselves. They themselves are objects stored on the heap, 
however, files store their data on disk; the file object is used by your 
program as an Interface to the disk file. 
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Each of these class-types (except for files, as e^lalned Delow) has a set of 
methods that allow you to 

• Add members to the collection. 

• Delete members from the collection 

• Allocate new space for the collection 

• Remove unused space allocated for the collection. 

In addition, each collection type has a co r respond i ng class-type that defines a 
scanner for that type of collection A scanner is an object that is used to 
move through a collection, acting in some way on each member in turn. 
scanners are used, for example, to search for particular collection members. 

You can also use scanners to add and delete collection members, but those 
operations are typically done through methods of the collections. The 
advantage of using scanners is that your current position in the collection is 

maintained for you 

files, unlike other collections, can only be accessed through fUeScamers. 

23.1 TUst 

TUst defines an object that maintains a list of objects-references. 

A list is similar to a Pascal wray [urize] OF object-references. The entire 
list is stored as one variable-length, contiguous object of type TUst Because 
list elements are object-references, elements of different lists (or multiple 
elements of a single list) can refer to the same object 

232 TArray 

An array is similar to a list but where a list contains objec t-refe rences, an 
array contains records. It is similar to a Pascal ARRAY [USEE] OF any type. 
While an object can have references to it in several lists, an item can 
normally be in only one array at a time. (Actually, you could put 
object-references in an anav, and then the array would be equivalent to a list 
The interface to lists is designed for use with object-refere n ces, however, 
while the interface to arrays is not) 

233 TStiing 

A string is a one-dimensional array of characters, similar to a Pascal ARRAY 
[l_size] OF CHAR The character string itself is stored in the string object; 
any particular string of characters can exist in only one string object 

Each element of a satring occupies one byte of memory. An element of an 
array occupies at least two bytes of memory. 

233 TFlle 

A file is similar to a string in the sense that it is used to handle a string of 
characters. A file, however, acts as an interface to a disk file. When you 
create a file object, you specify an OS p at h name. The ToolKit checks to see 
if a file with that name exists. If it does, the length of the file in bytes is 
put into the size field of the file object and a call to flleJBdsts Tetums 
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TRUE. The file is not opened however. If the file does not exist, a (zero) 
Is put into the fllasize field and a call to fil&Exists returns FrtJSE. 

TTie disk file is opened when you create a fUeScamer for the file object 

The method ni&Scanner opens the file for read and write access. To open the 
file for more limited access, use fil&ScameiFrom. See the Operating System 
Reference Manual for the Lisa for details on file access options and error 
codes. 

ZA Scanners 

seamen are objects used to scan lists, strings, arrays, or files and operate on 
every member, search for something, or assist in locating the correct point to 
insert, replace, delete, and so on. This section discusses how to use scanners 
to manipulate your collections. 

All scanners are instances of d es c endants of TScamer. Every type of 
collection has a corresponding type of seamen you use an instance of 
TUstScamer, TAnayScamer, TFUeScamer, or TStringScamer. Each of the 
collection classes has a Scanner method, which Is a function that returns a 
scanner object of the correct type, scanners are used and then thrown away; 
they generally are used to go once through a collection, in fact, when a 
scanner reaches the end of a collection the scanner automatically frees Itself. 

Every scanner object has a position field, scamer^osltlon is the point in the 
collection presently occupied by the scanner. The position is the index number 
of the last member of the collection returned by the scanner, unless the 
scanner is new. By default, new scanners have a position of 0, which is the 
position before the first member, scanners can, in general, start in any 
position, however. Reverse scanners begin with a position Just past the end of 
the collection 

When you create a scanner, you can specify its scanDirection A 
scanDirectton of scanBackward means that the scanner moves towards the 
beginning of the collection; a scanDirection of scanForward means that the 
scanner moves towards the end of the collection Every time you call the 
method scamer-Scan the position moves one member In scanDirection 
fUeScamers can only have a positive scanDirection files can only be seamed 
toward the end. The default scanDirection for all scanners is positive. 

When a scanner is first created you can specify the Initial postioa You do 
that by specifying the Index number of the first member to be returned by the 
scanner. When the scanner is created scamer.posltion is that index number 
plus or minus one, depending on scanDlreotlon 

Every time you call scamer.Scan which is a function, you get a BOOLEAN 
return value, and a return parameter. The return value Indicates whether or 
not the scan Is finished. It is finished when scamer-position is past the last 
member of the collection if scanDirection is positive; or when scamer-positlon 
Is before the first member of the collection if scanDirection is negative. The 
return parameter is the next member in the collection in scanDirection 
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Because scarmer.po$iUon Is updated when scannenscan 1$ called, 
scanner-position indicates the index number of the returned member. The 
returned member is referred to as the current member: 

When scamanScan Is called after the last member was returned, the return 
value is Frt-S£, and the returned member parameter is Nfc. or CHR((Q, 
depending on the type of the collection. When you are done with a scanner 
before the last member has been reached, call.scamerrtone. After that call, 
the next call to scamer-Scan returns FALSE, but the returned member 
parameter is left unch a nged. The scanner then frees Itself. 

During a scan, objects can be inserted before or after the current position, and 
the current member can be deleted or replaced. 

You can have more than one scanner on the same collection at the same time, 
but if you do, you cannot insert or delete using these scanners. 

All types of scanners are used in the same way. The general format is: 

VAR siTSoamer; 

member TMember; 
kTCollection; 



sr-LScamer; 
WHILE &Scan(member)DO 
BEGIN 

fcode here accessing member} 

EM3; 

Creating the scanner with s ?■ LScamer sets the scan position to a point Just 
before the first element in the list If you want to set an inital position and 
scanDirectioa use the method ScamerFrom to create the scanner. Each 
execution of the WHLE loop 

• Advances value of Lscanner^iosiUon by 1. 

• Sets member to the next member of the coilecttoa When the collection is 
a list, member is an object-reference. When the collection is a string or 

a file, member is a character. When the collection is an anay, member is 
a pointer to a record. 

• Runs the code in the WHILE loop. 

When the scan position reaches a point Just after the last element in the list 

• fcScan returns FALSE. 

• obj is set to ML, for lists and arrays, or CHRQJ) for strings and files. 

• The scanner frees itself. 
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When the purpose of the loop Is to search for a certain element call sDone 
when the element being searched for is found. Then 

• The next &Scan returns F^-SE. 

• The object variable retains its assigned value. 

• The scanner frees Itself. 

The following example illustrates the use of a listScamer to peel every banana 
in a bunch of bananas and remove the rotten ones, if an underripe banana is 
encountered no more bananas are peeled. 

PROCEDURE CheckBananas (bunch: TUst JOF Bananaft 
Vtf* s: TUstScarmer; 

be TBanana; 
BEGIN 

s r- bunchScamer; [Create a scanner to scan bunch) 
WHILE s£can(b) DO fox each b in bunch do:) 
BEGIN 

bPeel; (Tell b to Peel itself.) 

If (underripe THEN task b if it is underripe) 

sJDone pf so, force the scan to terminate.) 

ELSE F luotten THEN (Ask b if it is rotten.) 

sJDelete (TRUE); {If so, tell s to delete b from bunch and 
free it) 
END; 
END; 

2A1 FileScarmers 

file objects, unlike other collection objects, can only be accessed through 
scanners. 

Once the fileScamer is created, further references to the file object act as if 
the contents of the file were a string stored on the heap. The contents of the 
disk file are not moved to the heap, however (they are paged through buffers 
in the OS), so file operations can take longer than string operations. If no disk 
file with the given name exists, the file is created when the ftieScamer is 
created, and the file object acts like an empty string. Note that the ToolKit 
does not explicitly tell you whether or not the file existed before you created 
the fileScanner. 
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UDraw 



3.1 Introduction 

UDraw provides graphics routines for drawing in ToolKit programs. It must 
be used with all ToolKit applications. The functions UDraw provides include 
most of the functions provided by QuickDraw, v except that UDraw uses 32-bit 
long integer ft-ONQlNT) coordinates instead of l&-bit integer (INTEGER) 
coordinates. UDraw also provides a few extra functions. 

Using long integer coordinates provides coordinates that can range from 
-2147483648 (-2 31 ) to 2147483647 (2 31 -lX However, no single object can 
have a size greater than 2 15 in either dimension. 

This chapter assumes that you are familiar with the QuickDraw 
documentation, which is contained in the Pascal manual. 

UDraw defines TAraa, TPa& and TBranchArea 

TArea implements methods for all parts of an application that draw on the 
screen, including bordered areas, such as windows and panels. 

TPati, which is a subclass of TArea, implements methods that take information 
drawn in an application's view, and display it on the screen. 

TBranchArea, which is also a subclass of TArea, is used internally to maintain 
splittable panels. There is a reference sheet for TBranchArea in Part II of 
this manual. Because you do not deal directly with this class, it is not 
discussed further in this chapter. 

3.2 The Purposes of UDraw 

UDraw exists for two main purposes. First, it defines the basic graphical 
structures that characterize ToolKit applications: bordered and unoorderea 
screen areas. Second UDraw translates graphics from ToolKit formats to 
forms that can be used by QuickDraw. QuickDraw does all on screen drawing 
on the Lisa 

QuickDraw always draws in a grafPort A grafPort is a software-defined port 
that connects your application's drawing routines to the screen. When you 
want to draw, you focus the grafPort on some part of the screen. 

You normally do not need to worry about focusing in ToolKit programs, you 
draw in your view, using the view coordinate drawing routines implemented in 
UDraw and described in this chapter, some of your application's methods are 
called with the grafPort already focused and ready to draw in a pane or on a 
page. Other methods are called for a whole panel, and must call the method 
TPaneLOnAllPadsDo, which focuses on each pane in turn. 

You use the drawing routines defined in UDraw, rather than the similar 
routines in QuickDraw, because the UDraw routines use long integers, allowing 
specification of larger coordinates than QuickDraw can handle. UDraw 
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converts your long Integer coonflnates to Integer coordinates, scaling the 
coordinates and adjusting the grafPort so that the drawing appears correctly. 
Alternately, a set of conversion routines is provided so that you can convert 
long integers to integers yourself, which in certain circumstances is more 
efficient UDraw can scale coordinates automatically to handle pads with 
difference resolutions (primarily used for low and hicp resolution printing) or 
for zoom factors. 

You can call QuickDraw routines directly, as* long as you observe the 
following restrictions: 

• Your application's view does not print or zoom. 

• The view must be small enough to use 16-bit integer coordinates. 

If you want, you can use QuickDraw directly for drawing on the screen, and 
use UDraw when printing, but you will then need different code for each 
operation. 

33 The UDraw Classes 

UDraw provides the classes TArea and TPaL TArea defines a screen area 
with a border. TPad provides drawing and conversion routines used to display 
part of a view on the screen. Reference Sheets for these classes are 
provided in Chapter 7. 

33.1 TArea 

You generally do not use TArea or its methods directly. Instead you use 
TWlndow or TPanel which are subclasses of TArea IBand a class that is 
rarely used in applications, is also a subclass of TArea These classes are 
defined in UABC and are described in Chapter 4. 

TArea defines an area on the screen with a border. This area is defined by 
two rectangles: outeiRect, which describes the whole area including the 
border, and imeiRect which excludes the border. You can look at these 
variables to find the size of an area but do not change their values. To 
change the size of an area use the methods SetOuteiRect and SeUnreiRect. 

Methods of TArea take care of functions such as setting the size of an area 
drawing the frame, erasing the contents of the area and focusing. 

3A2 TPad 

Tpad is a subclass of TArea It provides methods to convert between view 
coordinates and GrafPort coordinates. These methods are called by the utility 
routines that do drawing in view coordinates (see Section 3.5 UDraw 
RoutinesX You can use these methods directly to increase efficiency by 
avoiding conversion operations fox every routine called. 

The grafPort is always focused on some Instance of a descenda n t of TPad 
whose handle is stored in the global variable thePad in essence, a pad is the 
place where drawing actually occurs. Drawing is only done on a single pad at 
a time. Which pad it is, however, is taken care of by the ToolKit Instances 
of TPane, a subclass of TPad are usually used as thePad 
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3.4 7T«UDraw Routines 

Tne Udraw routines provide functions similar to QuickDraw, using long integer 
view coordinates in place of QuickDraw's integer grafPort coordinates. Udraw 
also adds some other functions for both grafPort and view coordinates. 

These routines can be called to perform drawing operations in the view. All 
necessary conversions between view and grafPort coordinates are done by the 
view coordinate drawing routines. You can do conversions yourself to avoid 
unnecessary calculations, and then use the grafPort coordinate drawing 
routines in QuickDraw. 

33 When To Use the Conversion Routines 

The conversion routines can be used when your application uses grafPort 
coordinates for a series of operations. Since all on-screen drawing occurs 
in grafPort coordinates, every view coordinate UDraw routine first 
converts from view to grafPort coordinates, and then calls a grafPort 
coordinate routine in QuickDraw. You can, if you wish, call the 
conversion routines yourself, and then use the converted values In calling 
grafPort coordinate routines directly. 

3c6 Variables Declared In UDraw 

A number of variables are declared in the unit UDraw. 
the most useful of them. 



This section describes 



5&.1 Constants 

The following variables are used as constants in UDraw, and are shown 
here for your use. 



zeroPt: 
zeroRect: 



Point 
Rect; 



huoeRect: Rect; 



zeroLPt 
zeroLRect: 



LPotat; 
LRect; 



point with grafPort coordinates of (0,0) 

grafPort coordinates for a rectangle with 

topLeft and botRight both (0,0) 

rectangle with topLeft (0,0) and botRight 

(MAXirsn'/2^IAXlNT/2) 

point with view coordinates of (0,0) 

view coordinates for a rectangle with topLeft 

and botRight both (0,0) 

rectangle with topLeft (0,0) and botRight 

(MAXLINT/2J v tAXLINT/2) 

3£2 orthogonal conversions 

The following array is for performing orthogonal conversions by mapping v to 
h and vice versa. 

orthogonal: fiPRAY [vjhj OF VHSetect 

The value of ortho g onal is an enumerated type: either v or h. orthogonejfv] 
has a value of ft and o rthogonapi] has a value of v. 



hugeLRect: LRect 
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S£3 Pen States for Hl^m^iUng 

The following array is used to set the QuickDraw pen state for highlighting. 

Natter* /«RAY HH^iTransit] OF PenState; 

The value of hlg^Perfhfcymanslt) is a pen state. hkjiTranslt has a value that 
depends on the state of hicytilcyiUng at that time, and on what highlighting is 
desired, from the set (hNone, hOffToDinv roffToOn, hDlmToOn hDlmToOff, 
hOnToOff, hOnToDIm). WoJf^erthfcjVTransit] has as its value the correct pen 
state setting to produce the required hig^U^iting. 

3&A Patterns In View Ooonfinates 

Pen patterns are central to drawing on the Lisa display. QuickDraw defines a 
number of standard patterns. The following provide the same patterns in view 
coordinates. 

IPatVfflftte: LPattem Maps to QuickDraw pattern white. 

lPatBladc LPattem; Maps to QuickDraw pattern black. 

PatGray: LPattem Maps to QuickDraw pattern gray. 

lPatLtGray. LPattem; Maps to QuickDraw pattern ltGray. 

FatDkQray: LPattem; Maps to QuickDraw pattern dkGray. 

3j6J5 Graphics Areas 

A region in QuickDraw is an part or group of parts of a graphical object A 
region does not have to be contiguous, although in the ToolKit all of a single 
region must be in a single view. 

focusRgrt RgnHandte The part of the pad that needs to be updated. 
thePack TOacb The pad currently focused on. 

3j6u6 Conversion Pad (noPatf 

The conversion pad is provided so that you can call cetain methods of TPad 
when you need to, without needing to create a new pad object* and without 
changing any values in thePad. 

noPacfc TPofc Dummy pad that can be used to convert 

between short and long integer coordinates 
without arithmetic on the coordinates. For 
example: 

noPadRectToLREcKrectl. iRectifc 
sets IREctLtop to rectLtop. it performs 
similar operations on the other three 
coordinates. 
3u7 The UDraw Utility Routines 

This section describes the utility procedures and functions implemented in 
UDraw. These routines are not methods; methods of the classes defined in 
UDraw are described in the referenc e sheets for the classes: TArea, 
TBranchArea, and TPad. 

Since these are global procedures and functions, you can use them at any 
time, from any part of your program. 
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3J.1 Arithmetic and Utility operations 

UDraw defines a number of arithmetic and utility procedures and functions 
that may be useful in your program. Most of these correspond to standard 
Pascal language functions. UDraw reimplements those to use long integers. 
A few others are additions you may find useful 

PROCEDURE BoolToStr (boot BOOLE/** str. TPstringfc 

BoolToStr returns a string (str) containing TRUE if boot is true, FALSE if it is 
false. 

FUNCTION issmaupt (arcPt: LPOint)c BOOLE/V* 

IsSmallPt returns TRUE if both coordinates of the point can be opressed in 
grafPort (INTEGER) coordinates. 

FUNCTION isSmaURect (srcRect: LRectfc BOOLE/** 

isSmallRect returns TRUE if the coordinates of the rectangle can be 
expressed in grafPort (NTEGER) coordinates. 

FUNCTION UntDMnt 0: LONGBNT; * NTEGER)t LONGUNT; 

FUNCTION UntDi VL*lt (t > LONQIsfT> LONGasfT; 

These functions return the result of a long integer, t divided by J. UntDlvmt 
takes an integer as a divisor; UntDhrtJr* takes a long integer as a divisor. 
This acts like the Pascal ON operator. LWDlvlntflJ) is identical to i DIV J in 
results and similar in performance. However, IritDwUritQJ) is much faster 
than 1 DIV ] (when i and J are LONGINTX but it may not produce the correct 
result in all cases. 

FUNCTION LlntMuilnt (b LONGONT; J: iMTEQERfc LONGBMT; 

UntMuilnt returns the result of i multiplied by J. It is faster than i*J when i 
or J is a LONGBNT. 

FUNCTION UntOvrtnt Qb LONGOMT; $ BsTTEQER): LONGtfNT; 

Uses the formula Q+Jfty] to round i/J to the nearest LONGBMT. 

FUNCTION Max 0, > LONQWT> LONGWT; 

Max returns the larger of two numbers. 

FUNCTION Mto & J: LONGWT} LONGONT; 

Mn returns the smaller of two numbers. 

PROCEDURE PopFOCUS; 

PopFocus restores the last focus pushed onto the focus stack with PushFocus. 
The current focus is lost 
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PROCEDURE PushFoous; 

PushFocus stores the current grafPort focus on the focus stack. Use 
PopFoous to restore It 

PROCEDURE Reduce (VKR numerator, denorrtnaton INTEGER); 

Reduce reduces the fraction numerator/denominator to its lowest whole 
number terms. Note that the values of numerator and denominator may 

change. 

PROCEDURE ResizeFeedback (mousePt: Pi**; mtaPt, ma*>t: Point; outerRect: 
Rect; tatoHeight sbWMth, sfiHeigrrt: INTEGER; V/« newPt: Point* 

This procedure is used to draw the temporary lines displayed when the user is 
resizing a panel, pane, or window. It is called automatically in those cases 
but you can call it yourself to implement similar feedback. 

3.7.2 Graph Functions 

Most functions and procedures defined in this section have two versions: one 
for grafPort coordinates and one for view coordinates. Each version operates 
identically, except that operands and results in the view coordinate routines 
are longbmts, and operands and results for the grafPort coordinate routines 
are INTs. In every case, the first routine given is the grafPort coordinate 
routine. You can tell the routines apart by their names: the names for 
grafPort coordinate routines usually contain Pt (for point) or Rect (for 
rectangle), while the names for view coordinate routines usually contain LPt 
(for long point) or LRect (for long rectangle). 

3.7.Z1 Arithmetic on Points 

PROCEDURE PtPlusPt (operandi, operants Point; VftR result: Point); 

PROCEDURE LPtPlusLPt (operandi, cperano^ IJ>crinC V/« result: LPoinQ; 

FUNCTION FPtPlusPt (operandi, operandi Point* LONGBMT; 

The two procedures add the coordinates of ope ra n di to the coordinates of 
operandi and return the result in result The function adds the two points, 
and gives the result as the return value. 

Because functions cannot return a Point the result is returned as a LONG3NT, 
which can be coerced into a Point For example, where pt is of type PONT, 
you can use pb- PolntCfPtPlusPttpU, pt2fc to convert the result to a POINT. 

In all cases, operandi and operand2 are unchanged. 

PROCEDURE PtMlnusPt (operandi, operandi Point; VW result: Point* 

PROCEDURE LPtMbTuslPt (operandi, operandi LPqtnt; Wft result: LPtrint* 

FUNCTION FPtMfrusPt (operandi, operandi Point* LONGBNT; 

The two procedures subtract the coordinates of operandZ from the coordinates 
of operandi, and return the result in result The function performs the same 
operation, but gives the result as the return value. 
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Because auctions cannot return a Point the result is returned as a LONGINT, 
which can be coerced into a Print. See FPtPiusPt for an example of 
coercion. 

In all cases, operandi and operancE are unchanged. 

PROCEDURE PtMUUr* (operandi: Pi**? cperancE: INTEGER; Wft resrtfc 
Point); 

PROCEDURE LPtMulIftt (operandi: LPoint operancE: NTEGER; VffK result: 
LPoint); 

FUNCTION FPtMulirit (operandi: Point; operandi BMTEGER* LONGINT; 

The two procedures multiply both coordinates of operandi by operancE and 
return the result in result The function multiplies the two operands, and 
gives the result as the return value. 

Because functions cannot return a Point the result is returned as a LONQINT, 
which can be coerced into a Point See FPtPiusPt for an example of 
coercion. 

In all cases, operandi and operancE are unchanged 

PROCEDURE PtDlvmt (operandi: Point operancE: UTEGER; VAR result 
Point); 

PROCEDURE LPtDivim (operandi: LPoint- operancE: BMTEGER; vpr result 
LPoint); 

FUNCTION FPtDlvlnt (operandi: Point operancE: lMTEGER): LONGINT; 

The two procedures divide both coordinates of operandi by operancE and 
return the dividend in result The function divides the two operands, and 
gives the dividend as the return value. 

Because functions cannot return a Point the result is returned as a L0NC3NT, 
which can be coerced into a Point See FPtPiusPt for an example of 
coercion. 

In all cases, operandi and operancE are unchanged. 

FUNCTION Equa*>t (operandi, operancE: PoinQe BOOLE** 

FUNCTION EtyfiBJPt (operandi, operancE: LPoin$ BOOLE/*fc 

These procedures compare the two points and return TRUE if they are equal 
orF^SElf not 

FUNCTION FPtMaxPt (operandi, c^erancfi: PohiQ: LONGt^T; 

This function returns a point with coordinates equal to the largest of the two 
corresponding coordinates in the operands. The maximum of each coordinate 
is taken separately; therefore the return value may not be either of the two 
points given as operands. It may be a combination of the two. 
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FUNCTION FPtMlnPt (operandi, operandi Roma LONGBNT; 

This function returns a point with coordinates equal to the smallest of the 
two corresponding coordinates in the operands. The minimum of each 
coordinate is taken separately; therefore the return value may not be either 
of the two points given as operands. It may he a combination of the two. 

FUNCTION FDIa^ect (rectangle: Rect* LONQNT; 

This function returns a point designating the<lower rigfit comer of rectangle 
as if the upper right comer is at (OA 

Because functions cannot return a Point the result is returned as a LONGUNT, 
which can be coerced into a Point See FPtPiusPt for an example of 
coercion. 

PROCEDURE PointToSti (pt Poink stn TPstringfc 

PROCEDURE LPointToStr (pt LPoinfc stn TPstringfc 

These procedures convert pt to the string str. 

3J22 Arithmetic on Rectan^es 

FUNCTION EmptyRect (r Recft BOOLEAN; 

FUNCTION EmptyLRect (n LRect> BOOLE/** 

These procedures return TRUE if the given rectangle is an empty rectangle or 
FfiLSE if not A rectangle is considered empty if the bottom coordinate is 
equal to or less than the top or the right coordinate is equal to or less than 
the left 

FUNCTION EqualRect (rectA, iectB: Rec$ BOOLErtt 

FUNCTION EquaURect ftectA, rectB: LRecQc BOOLEAN; 

These procedures compare the two rectangles and return TRUE if they are 
equal or FALSE if not The two rectangles must have identical boundary 
coordinates to be considered equal. 

PROCEDURE RectMnusRect (operandi, operandi Reef VAR result Recti 

PROCEDURE LRectttnusLRect (operand^ operandi LRecf VAR result: 
LRectfc 

These procedures subtract the operants rectangle from the operandi 
rectangle, returning the result in result 

PROCEDURE RectPlusRect (operandi* operandi Reel; V/« result Rectfc 

PROCEDURE LRectPiusLRect (operandi, operandi LRect; V** result: LRectfc 

These procedures add two rectangles and return the sum in result 
Rectangles are added by adding their c o rres p onding top left and bottom right 
coordinates. 



3-9 



Lisa ToolKit Reference Manual UDraw 

5J23 Operations on Rectangles 

PROCEDURE Aligftect (W« dstRect Rect; srcRect Rect; vte: VHSelect); 

PROCEDURE AUgnLRecl (VW destLRect' LRect; snlRect LRect; vhs: 
wsetecft 

These piocedures change dstRect to match srcRect In the vr» direction. 

FUNCTION L^ngtmect (n Rect; vhs: WSetecyc FsTTEGER; 

FUNCTION LengthLRect (K LRect; Vhs: VHSelect): LONGBNT; 

These procedures return the length of the rectangle side In the tf* dlrectioa 

FUNCTION RectHesPt (destRect: Rect; pt: Point): BCCtjEi^H- 

FUNCTION LRectHasLPt (destLRect LRect; pt: LPotnt): BOOLEAN; 

These procedures determine if the point Is Inside the rectangle and return 
TRUE if so or FA.SE if not These procedures check if pt is greater than or 
equal to the top left point and less than or equal to the bottom rig^t point of 
the destination rectangle. (QuickDraw's PUnRect procedure returns FMJSE if 
the topleft point is equal to the bottom rig^t point) 

PROCEDURE RectHavePt (dstRect Rect; VW pt: Pointy 

PROCEDURE LRectHaveLPt (destLRect LRect; WK pt LPolnft 

These procedures force the point to be inside the rectangle if it is not by 
changing the point so that pt is greater than or equal to the top left 
coordinate of the rectangle, and less than or equal to the bottom right 
coordinate. (topLeft <- pt <- botRkprt) 

FUNCTION RectsNest (outer, Imer: Rect* BOOLE/W 

FUNCTION LRectsNest (outer, Jnnen LRect): BOOLEAN; 

These procedures determine if the Imer rectangle is inside (or touches) the 
outer rectangle and return TRUE if so, FALSE if not 

PROCEDURE RectifyRect QtfiR dstRect Rectfc 

PROCEDURE RectlfyLRect (v/« destLRect LRect); 

These procedures exchange opposing coordinates of a rectangle until the top 
left coordinate Is less than or equal to the bottom ricfrt coordinate. 

FUNCTION RectlsVisibte (rectlnPort: Rect* BOOLE/** 

FUNCTION LRectlWfctote (srcLRect LRect): BOOLE** 

These procedures return TRUE if the rectangle Intersects the current update 
region. The grafPort must be focused on the view containing the rectangle. 
You can call LRectlsVtetote to test whether a part of your document requires 
drawing. You can speed up your application by not drawing parts that cannot 
be seen by the user. 
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PROCEDURE RectToStr (n Rect; $tn TPstringJt 

PROCEDURE LRectToStr (k LRect; ttr. TPstringfc 

These procedures convert the rectangle r to the string str. 

3l73 Calculations with Rectangles and Points - View Coonflnates 
PROCEDURE SetLPt &m dBStPt LPoint; itsH ItSV. LONGBNTi 

SetLPt assigns two LONGONT coordinates to a variable of type LPolnt 

PROCEDURE SettJRBCt (V/« dstRect: LRect; ttsLert, IteTop, ttsRfcpit, 
itsBottont LONGaNTk 

SetLRect assigns the four boundary coordinates to the rectangle dstRect The 
result is a rectangle with coordinates atsLefUtsTopJtsRlpMits8otton>). 

This procedure is supplied as a utility to help you shorten your program text 
If you want a more readable text at the expense of length, you can assign 
LONQINTs (or Lpoints) directly into the rectangle's fields. There is no 
significant code size or execution speed advantage to either method. 

PROCEDURE OffsetLRect (WK dttRBCt: LRecfc dft dv: LONG8NT); 

OffsetLRect moves the rectangle by adding on to each horizontal coordinate 
and &f to each vertical coordinate. If an and dv are positive, the movement 
is to the right and down; if either is negative, the corresponding movement is 
in the opposite direction. The rectangle retains its shape and size; it is 
moved on the coordinate plane. This does not affect the screen unless you 
subsequently call a routine to draw the rectangle. 

PROCEDURE InsetLRect (V** dstRect: LRect; dh, dv: LONGflNTt 

InsetLRect shrinks or expands the rectangle. The left and right sides are 
moved in by the amount specified by dh; the top and bottom are moved 
toward the center by the amount specified by dv. If dh or dv is negative, the 
appropriate pair of sides is moved outward instead of inward. The effect is 
to alter the size by 2*dh horizontally and 2«dv vertically, with the rectangle 
remaining centered in the same place on the coordinate plane. 

If the resulting width or height becomes less than 1, the rectangle is set to 
the empty rectangle (QJOJOJfy. 

FUNCTION SeotLRBCt (srcRectA, srcRectB: LRect; VfiR dstRect LRect* 
BOOLEAN; 

SectLRect calculates the rectangle that is the intersection of the two input 
rectangles, and returns TRUE if they indeed intersect or FALSE if they do 
not Rectangles that "touch" at a line or a point are not considered 
intersecting, because their intersection rectangle (really, in this case, an 
intersection line or point) does not enclose any bits on the bitmap. 
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If the rectangles do not intersect the destination rectangle is set to (CLOAO). 
SectRect works correctly even if one of the source rectangles is also the 
destination. 

PROCEDURE untanLRect (srcRectA, srcRectB: LRect; VAR dstRecU LRectfc 

UMorlRect calculates the smallest rectangle that encloses both input 
rectangles. It works correctly even if one of the source rectangles is also 
the destinatioa 

FUNCTION LPtlnLRect (pfc LPoint; n LRect* BOOLE/W 

PtinLRect determines whether the pixel below and to the rigfit of the given 
coordinate point is enclosed in the specified rectangle, and returns TRUE if 
so or false if not 

3.7.4 Drawing Operations for View Coordinates 

The following routines are similar to QuickDraw calls, but use long integers 
(view coordinates) so that they can perform graphics in the view. See the 
Lisa Pascal appendix on QuickDraw for the corresponding routines for 
grafPort coordinates. In general, the grafPort routines are identical to these, 
except that the routine name does not have the L that indicates these are for 
long integers. 

You must focus the grafPort on your view before calling these routines. 

3.7A1 Line-Orawing Routines 

PROCEDURE MoveToL (T\, V: LONG1NT); 

MoveToL moves the pen to location (*w) in view coordinates. No drawing is 
performed. 

PROCEDURE MoveL (dh, d* LONGING 

MoveL moves the pen a distance of dh horizontally and dv vertically from its 
current location; it calls MoveToUh^fiv^dvX where Giv) is the current 
location in view coordinates. The positive directions are to the right and 
down. No drawing is performed. 

PROCEDURE UneToL (ft, V. LONGBMTfc 

LlneToL draws a line from the current pen location to the location specified 
On view coordinates) by h and v. "me new pen location is ffw) after the line 
Is drawn. 

PROCEDURE UneL (ctv dv: LONQNTk 

UneL draws a line to the location that Is a distance of eft horizontally and ft 
vertically from the current pen location; it calls UneToLf>^tw*ftX where 
Qvi) is the current location. The positive directions are to the ricjrt and 
dowa The pen location becomes the coordinates of the end of the line after 
the line is drawn. 
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3JA2 Graphic Operations on Rectanjpes 
PROCEDURE FrameLRect Ort LRectfc 

FrameLRecl draws an outline Just inside the specified rectangle, using the 
current views pen pattern, mode, and size, "me outline is as wide as the pen 
width and as tall as the pen heiGpt It is drawn with the the current pen 
pattern (pnPaQ, according to the pattern transfer mode (pnMode). The pen 
location is not changed by this procedure. 

PROCEDURE PalntLRect (p. LRectfc 

PaintLRect paints the specified rectangle with the current pen pattern and 
mode. The rectangle on the bitmap is filled with the pnPaC according to the 
pattern transfer mode specified by pnMode. The pen location is not changed 
Hy this procedure. 

PROCEDURE EraseLRect (n LRectJt 

EraseLRect paints the specified rectangle with the current GrafPorfs back- 
ground pattern bkPat On patCopy mode* The GrafPorfs pnPat and pnMode 
are ignored; the pen location is not changed. 

PROCEDURE InvrtLRect (n LRectfc 

InvrtLRect inverts the pixels enclosed by the specified rectangle: every white 
pixel becomes black and every black pixel becomes white. The GrafPorfs 
pnPaC pnMode, and bkPat are all ignored; the pen location is not changed. 

PROCEDURE FillLRect fc LRect; iPat: LPaUemfc 

FUlLRect fills the specified rectangle with the given pattern On patCopy 
mode). The GrafPorfs pnPat pnMode, and bkPat are all ignored; the pen 
location is not changed 

3.7A3 Graphic Operation s on O/ais 
PROCEDURE FrameLOval (n LRecti 

FrameLOval draws an outline Just inside the oval that fits inside the specified 
rectangle. The outline is as wide as the pen width and as tall as the pen 
height It is drawn with the pnPat, according to the pattern transfer mode 
specified ^ pnMode. me pen location is not changed by this procedure. 

PROCEDURE PamtLOval fr LRect* 

PaintLOval paints an oval Just inside the specified rectangle. Tne oval is 
filled with the pen pattern pnPaC according to the pattern transfer mode 
specified by pnMode. The pen location is not changed by this procedure. 

PROCEDURE EraseLOval (p LRectfc 

EraseLOval paints an oval just inside the specified rectangle with the current 
background pattern bkPat Qn patCopy modeX The pen pattern pnPat and the 
pattern transfer mode pnMode are ignored; the pen location is not changed. 
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PROCEDURE tavrtLOvel (r LRect* 

InvrtLOval Inverts the pixels enclosed by an oval Just inside the specified 
rectangle: every white pixel becomes black and every black pixel becomes 
white. The pnPaC pnMode, and t*Pat are all ignored; the pen location is not 
changed. 

PROCEDURE FlULOvel (r LRect; Fat LPsttemfc 

FWLOval fills an oval just inside the specified iectangle with the given 

Sttem (in patOopy modeX The GrafPort's pnPaL pnMode, and bkPat are all 
_iored; the pen location is not changed. 

3JAA Graphic operations on Rounded-Comer Rectangles 

PROCEDURE FrameLRRect (r LRect; ovalWWtn ovalHei^t: INTEGER); 

FrameLRRect draws an outline Just inside the specified rounded-comer 
rectangle, using the current pen pattern, mode., and size. OvalWldth and 
ovaJHeig^t specify the diameters of curvature for the comers. The outline is 
as wide as the pen width and as tall as the pen height The pen location is 
not changed by this procedure. 

PROCEDURE PalntLRRect (r LRect; ovelWIdth, oveJHeigit: BMTEGERfc 

PeintLRRect paints the specified rounded-comer rectangle with the current 
GrafPort's pen pattern and mode. OvalWldth and oveJHeky* specify the 
diameters of curvature for the comers. The rounded-corner rectangle on the 
bitmap is filled with the pnPat, according to the pattern transfer mode 
specified t)y pnMode. The pen location is not changed by this procedure. 

PROCEDURE EraseLRRect (R LRect; ovaiwwm, ovaJHeW*: iMTEGERfc 

EraseLRRect paints the specified rounded-comer rectangle with the current 
GrafPort's background pattern bkPat On petcopy modeX OvalWldth and 
ovaJHefeyit specify the diameters of curvature for the comers. The GrafPort's 
pnPat and pnMode are ignored; the pen location is not changed. 

PROCEDURE mvrtLRRect fc LRect; OVelWk^ OVS^ei^fc INTEGER* 

mvrtLRRect inverts the pixels enclosed by the specified rounded-comer 
rectangle: every white pixel becomes black and every black pixel becomes 
white. OvalWldth and oveJHety* specify the diameters of curvature for the 
comers. The pnPat, pnMode, and bkPat are all ignored; the pen location is 
not changed. 



PROCEDURE FlULRRect (r LRect; OVelWkKh, oveJHe&*: UTEQER; Pat: 

LPattemfc 

FlULRRect fills the specified rounded-comer rectangle with the given pattern 
On petcopy modeX OvalWldth and oveJHe&it specify the diameters of 
curvature for the comers. The pnPst, pnMode, and bkPat are all ignored; the 
pen location is not changed. 
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37A5 Graphic Operations on Arcs and wedges 

These procedures perform graphic operations on arcs and wedge-shaped 
sections of ovals. 

PROCEDURE FrameLArc (n LRect; startAngle, arcAngie: INTEGER^ 

FrameLArc draws an arc of the oval that fits inside the specified rectangle, 
using the current GrafPort's pen pattern, mode, and size. StartAngte indicates 
where the arc begins and is treated mod 360, flrc^igie defines the extent of 
the arc. The angles are given in positive or negative degrees; a positive 
angle goes clockwise, while a negative angle goes counterclockwise, zero 
degrees is at 12 o'clock high, 90° (or -27tf) is at 3 o'clock, 180° (or -iao°) is 
at 6 o'clock, and 270° (or -90°) is at 9 o'clock. Other angles are measured 
relative to the enclosing rectangle: a line from the center of the rectangle 
through its top right comer is at 45 degrees, even if the rectangle is not 
square; a line through the bottom right comer is at 135 degrees, and so on . 

The arc is as wide as the pen width and as tall as the pen height It is 
drawn with the pnPat, according to the pattern transfer mode specified by 
pnMode. The pen location is not changed by this procedure. 

PROCEDURE PalntLAic (n LRecfc start/togie, arctagle: NTEGERfc 

PaintLAic paints a wedge of the oval Just inside the specified rectangle with 
the current GrafPort's pen pattern and mode. Startttigte and arcAngie define 
the arc of the wedge as in FrameArc. The wedge on the bitmap is filled with 
the pnPat, according to the pattern transfer mode specified by pnModa The 
pen location is not changed by this procedure. 

PROCEDURE EraseLArc (n LRect; staort/^, arc/togte NTEGERfc 

EraseLArc paints a wedge of the oval Just inside the specified rectangle with 
the current GrafPort's background pattern bkPat On patOopy mode). 
StartAngle and arcAngie define the arc of the wedge as in FrameArc. The 
GrafPort's pnPat and pnMode are ignored; the pen location is not changed 

PROCEDURE InvrtLArc Cr URbcC- start^gie, arc^gle: iMTEGER); 

InvrtLArc inverts the pixels enclosed by a wedge of the oval Just inside the 
specified rectangle: every white pixel becomes black and every black pixel 
becomes white. StartAngle and arcAngie define the arc of the wedge as in 
FrameArc The GrafPorrs pnPat, pnMdde, and bkPat are all ignored; the pen 
location is not changed. 

PROCEDURE F1ULATC (n LRect; Start/Vigte, mcfiOfB: 1MTEGER; Pait: 

LPatteir* 

FlULArc fills a wedge of the oval Just inside the specified rectangle with the 
given pattern On patbopy mode). StartArale and arcAngie define the arc of 
the wedge as in FrameArc. The GrafPort's pnPat* pnMode, and bkPat are all 
ignored; the pen location is not changed. 
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The Application Base Classes 

4wl What the ABC* Are 

Tne /^jpllcatlon Base Classes (ABC's) consist of predefined Clascal class-type 
definitions. 

The methods defined in UABC perform most of the automatic functions 
necessary for a Lisa application. They control screen display, scrolling, 
window size and resizing, menu display, command input keyboard input, and 
mouse handling. 

Aside from defining the objects necessary for the standard Lisa functions 
needed by applications, the ABC's structure the way an application is written. 
When a ToolKlt program is running, the ToolKlt calls certain application 
methods. You must write your application so that the correct methods are in 
the right places. This chapter contains descriptions of the important ABC's 
and also tells you what you are required to do, and what you can do, with 
each ABC. 

Several of the most important classes in UABC are always subclassed for use 
in application programs. When you create a subclass of one of these classes, 
you may add methods that add application-specific functions, and you may 
add data fields for the program's use. 

The following ABC classes are always or, in the case of TOommand, nearly 
always subclassed for use in application programs. 

• TView 

• TWlndow 

• TProcess 

• TDocMenager 

• TSelection 

• TCommand 

Each of these ABCs is fully described in its reference sheet in Part II of this 
manual. 

12 Which ABCs contain What Functions 

This section describes the most important functions handled by the ABC's that 
every ToolKlt application uses. 

IZ1 Tvlew 

Class TVtew is always subclassed at least once for use by your application. 
You can have multiple view objects in a single program. The views you create 
produce a complete visual representation of the entire set of objects that 
make up the visible data of the program. Each view object may be thought 
of as producing a picture that is something like a sheet of paper, which often 
is larger than the Lisa display, but which has definite boundaries. In some of 
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the original Lisa applications, such as LlsaDraw, and In all ToolKlt 
applications, you can scroll to a point where the white background stops, and 
a gray background 1$ visible. That border 1$ the border of the picture created 
by the view. 

What is visible on the display is normally only a part (or possibly several 
parts) of the view's entire picture. Which part of the view's picture is 
displayed is determined by the user, through the use of the scroll bars and 
the window and panel size control boxes. Thp application does not need to be 
concerned with what is actually seen on the screen, since the ToolKlt handles 
the display once the view is defined. The application can, though, ask the 
ToolKlt what parts of the view's picture are visible on the display, and use 
that information to speed display processing. 

Because Lisa applications are visually oriented the view often contains the 
most important references to the data In addition, all of the drawing Is 
always ordered through the view object 

4Z2 TWlndow, TPanet and TPane 

When writing an application, you always subclass TWindow, and then define 
the window's BlankStaUoneiy method to initialize a new document 

The window object and panel objects control the automatic screen functions. 
The portion of the display that they create Is essentially the entire border of 
the window that you see on the screen. The window object separates off a 
section of the display screen surrounding the entire visible portion of an 
application. Including the title bar and the scroll bars. The window object 
creates and controls the title bar and the window size control box 

The panel object creates the scroll bars, as well as the panel size control 
box. if there is one. Each panel object has two scroll bars, one on the ri^t 
and one on the bottom. The scroll bars can be suppressed, unless the panel is 
at the ricpt or bottom of a window with a size control box. or has a size 
control box itself. 

A window can contain a number of panels. 

Different panel objects usually display portions of different views. The views 
may be different representations of the same set of objects. For example, 
LisaGraph has two pa nels, one that displays a chart of the values and one 
that displays a graphical representation of the values. Panels in the same 
window may also display views of different objects; the Calculator, when used 
with its transaction tape, contains two panels. The calculator panel shows 
the calculation going on at that moment; the tape panel shows a record of all 
the calcul at i o ns performed. 

Creating a panel object also creates one pane object 

Each time the user splits a panel, one or more pane objects are added and 
one of the scroll bars is divided In two. The panes can each display a 
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different portion of the view looked on by that panel. The number of panes 
in a window is equal to the number of divisions of the window. 

The pane objects control the visible contents of the panel objects. It is the 
panes that determine what pans of the view objects are actually displayed 
although the user may change what can be seen in a pane by using the panel's 
scroll bars or the window's size control box Your application, however, never 
deals directly with penes. The current pane is assigned to the global variable 
thePad before your application is told to draw. You call routines defined in 
UDraw, and the ToolKit takes zooming factors into account, converts your 
long integers into simple integers, and calls QuickDraw to draw on the screen. 

*23 TProcess 

There Is always one and only one instance of a descendant of TProcess in any 

ToolKit application. 

The methods of TProcess are the methods of an application that do not apply 
to any one document For example, the routines that initialize libraries and 
communicate with the Desktop Manager are methods of TProcess. 

The most important function of the process object is in controlling the main 
event loop. ToolKit programs operate primarily in response to user events, 
such as menu commands, mouse clicks, and keyboard entry. Most of the time 
in a ToolKit program is usually spent waiting for some event When an event 
is received, appropriate methods from UABC, uobject, building blocks, or the 
application's units are called. When the methods complete, the event loop 
continues, unless the event caused a serious error (usually one that results in 
a "technical difficulties'' display), or ended the session 

The process object also handles errors, warnings, and termination it is the 
process object that displays m ess a ges from the phrase file. 

The process object for an application can still exist even when there is no 
view object, window object docManage r object, or selection object for that 
application in this case, the process is waiting for the user to activate a 
document (You may notice that every Lisa application takes longer to start 
up the first time it is used after the Lisa office system is started. This Is 
because the process for an application is created the first time a document 
that uses that application is opened after start up. When a document is put 
away, every object except the process is deallocatted. The process for that 
appl icatio n is kept until the Lisa turns off, waiting for the user to open a 
document) 

%2A T D ocManager 

There is one and only one instance of a de scen d a n t of TDocManager for every 
document icon or window managed by a process. It is created when the user 
first opens or displays the document 

The docManager object controls opening and closing the files used to store 
the state of the document, and also manages memory used for that document 
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Aside from creating a subclass and defining a CREATE method and a 
NewWindow method, you usually do not need to deal with the docManager. 

*23 TSelectlon 

Many actions or c o mmand s in Lisa applications act on some particular object 
within the set of objects used by the program. The object (or group of 
objects) acted on in such a case is called the selected object. 

The selection is the instance of "reelection or instance of a descendant of 
^Selection that receives commands and has ac6ess to any selected objects. 

There is always one selection for every panel object One panel in each 
window is designated the selectPanel which means that it contains the active 
selection object When a comman d is given, that command is sent by the 
ToolKit to the selection in the active window's selectPaneL Normally, the 
descendant of TSelectlon that you create declares a field to reference the 
selected object, or a list of the selected objects. Your command routines use 
that field to act on the selected object 

Note that a selection is not the same as a selected object The selection is 
an instance of TSelectlon or a descendant of TSeiectloa at least one of which 
always exists for each panel object Selected objects are objects displayed in 
the panel containing the selection. The selection may, however, be null, 
meaning mat there is no selected object TSetection defines a field that 
indicates the kind of selection A null selection is designated nothlntfOnd. 

If an object is selected, it normally is hicfilicptted in the view. Every 
TSelectlon descendant class should implement a Hfajrikjit method to visibly 
mark every selected object, and also to remove the mark when the object is 
no longer selected. 

Because so many menu and key com ma nd s involve the selection object 
command s are always handled through the selection. The selection may, 
however, delegate responsibility for a command to the window, the view, or to 
some other object 

4Z6 TCommand 

When the user selects a c omman d from a menu, or gives an Apple-key 
equivalent, the comm a n d is translated into a comm a nd number for use by the 
ToolKit and the application. Some commands change the contents of the 
document and some Just change the display, such as when a ruler is 
displayed When the c ommand changes the document unless the user is 
asking that a command be undone (that is, to have the effects of the last 
command reversed), the command number is used to create an instance of a 
d esce n dant of TCommand or, occasionally, an instance of TOommend itself. 
The new command object is then told to Perform the command. 

The comman d object is kept until another command is given If that 
command is an undo comman d the con ma d object Is told to undo itself. 
Some c ommand s cannot be undone, in which case the ToolKit gives the user a 
message to that effect but most can be undone. 
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If another undo command is given, the c ommand object is told to redo itself. 
This can continue indefinitely, with undo and redo alternating. 

In order to make undoing a com ma n d easier, command s are often implemented 
so that they do not change any data, but only change the view so that it 
appears as if the data has been changed. This is called applying a filterta 
the data After it is too late to undo the comman d, a separate step, 
performed by the method Commit actually carries out the operation on the 
data, and makes the effect of the command perrnanent 

When a c ommand is implemented so that it uses a filter, the way the view is 
displayed is changed. The original set of objects that make up the view is 
not altered. When the objects are displayed, however, a uftfeafimage of the 
objects is shown in place of the actual image. Figure 4-1 illustrates this. A 
command to recolor all the objects in the view was given by the user. When 
the view is displayed, the objects are first filtered so that they appear in the 
virtual view with the correct color. The actual view has not been changed 
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Figure 4-1 
Filtering 
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There is a method of TVIew called EaohVlrtuaPart EachViitualPart is one of 
a number of methods in the ToolKit that take a procedure as an argument 
These IteraUngimvmte apply the input procedure to a whole set of objects, 
one at a time, window, and Vtew£achVlrtutfPart do not themselves apply the 
input procedure; they each call other iterating methods, which then apply the 
procedure. 

TWlndow. or TVtew£achVirtualPart tests the most recent c an ma nd object to 
see if it has been done. (Remember that conrrand objects can in general be 
done or undone, undoing a command object removes its effects.) If the 
command has been undone. EachActualPart is called. EachActualPart which 
exists in both TVIew and TWlndow. applies the input procedure to each object 
in the document's data set 

If the command has been done. TWlndow. or TVlewfacnvtrtuaiPart calls 
commandJEachVlrtualPart for the most recent c ommand object 
commanclEachVirtuaPart applies the method comrnan d filter/VidDo to each 
object co mma n l FllterAndDo alters the object in the same way the command 
would, calls the procedure that was passed in as an argument to 
EachViitualPart and then changes the object back to its original state. 

For example, if the last command was to recolor the object and the 
procedure given as an argument to EachViitualPart is a Draw method 
Filter/VidDo first checks if the object was selected. (When comma n ds like 
this one are implemented, you must have some way of telling which objects 
were selected when the last command object was created.) If the object was 
not selected, it is simply told to Draw itself. If the object was selected the 
color is changed to what it should be after the c om mand and then the object 
is told to Draw itself. The object's color is then changed back. 

When a command that is not an undo comman d is given, the previous 
comman d object is told to Commit Itself (unless the command was undone and 

not redone), which makes the new actual view match the old virtual view. In 
the example given above, the object's color Is changed as the old command 
required. In Figure 4-1. the actual view would be changed to match the 
virtual view shown. Note that it is not necessary to invalidate any of the 
display at this point because it already reflects the changed state of the 

The old cu r ium tl object is then deallocated. A new com mand object is 
created for the new c ommand. 

43 Global variables 

UABC defines a number of global variables. These variables hold important 
values for the process, The global variables indicate the active window 
object (currentWlndow), identify the tool and the process, and hold a wide 
range of other values. These variables are doc u men t ed in Chapter 6. 
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M doted Procedures and Functions 

UABC defines a number of global procedures and functions. These provide 
services and utility functions needed throughout the ToolKit, and by 
application programs. The routines that might be used by applications are 
documented in Chapter 6. 



4-8 



Lisa ToolKlt Reference Manual ToolKit Debugger 



Chapters 
The ToolKit Debugger 



5.1 The Debugging Facilites . , .... ....5-2 

52 The Pulldown Debug Menu . ...... . .... 5-3 

5.2.1 Report Every Event 5-4 

522 Count Heaps after Commands 5-5 

5.2.3 Check List indices . 5-5 

52.4 Dump Process Globals . 5-6 

52.5 Dump Active Document Prelude 5-6 

52.6 Enable E>qperimental Features ...5-6 

52.7 Report Garbage In Document Heap ....5-7 

52.8 Free Garbage in Document Heap ...... 5-7 . 

52.9 EditDialog 5-7 

52.10 Stop Editing Dialog ., .5-7 

53 The Interactive Debugger ..... S-« 

53.1 Breakpoint 5-10 

5.32 ClearBreakpoints 5-12 

533 DebugStatus 5-12 

5.3.4 EntertisaBug 5-13 

53.5 FrameOump 5-13 

53.6 GO 5-13 

53.7 HeapDump 5-13 

53.8 Inspectdbject 5-13 

53.9 LeveisTowatch 5-14 

5.3.10 Memoryoump 5-14 

5.3.11 OutputTo....... 5-14 

53.12 Prompt 5-15 

5.3.13 RefsToObJect 5-15 

53.14 stackCrawl 5-15 

53.15 Tally & Time 5-15 

53.16 Watch 5-16 



5-1 



Lisa ToolKit Reference Manual ToolKit Debugger 



The ToolKit Debugger 



5A The Debugging Facilites 

The Lisa /^plications ToolKit provides two basic debugging facilities. One is 
a set of pull-down menu options that can be turned on while the program is 
running. Those options 

• Produce information on the dynamic state of the program. 

• Allow you to edit dialog boxes. 

• Enable or disable experimental program features. 

• Free objects left on the heap that have no remaining references. 

In addition, there is a separate interactive debugging menu, displayed on the 
alternate screen. The interactive debugger allows you to stop the application 
and 

• Examine the state of the process, document, objects, and object fields. 

• Step through the program at any pace you desire. 

• Dynamically trace the action of the program. 

• Analyze your program's perfoimance. 

The ToolKit interactive debugging menu allows you to also use the basic Lisa 
debugging facilites provided by Lisabug. However, although Lisabug has 
some functions similar to those provided by the ToolKit interactive debugger, 
Lisabug operates on the assembler level, while the Interactive debugger 
operates on the Clascal level. Lisabug is not discussed in this chapter. See 
the dubugger chapter of the Workshop manual for more information on 
Lisabug. 

The ToolKit debugging facilites work on ToolKit programs that are running on 
the desktop. You can also use the interactive menu to debug Clascal 
programs running under the Workshop. Note that you cannot access the 
pull-down menu options from the workshop. 

Another point to remember is that when any program has a fatal error on the 
Lisa, you drop into Lisabug, not into the ToolKit interactive debugger. If you 
want to find fatal bugs using the ToolKit debugger, you must do so by using 
breakpoints or by stepping through the program to determine exactly where 
the crash occurs. Lisabug will, however, allow you to find out some 
information about the state of the program after the crash. 

Some errors that are peculiar to ToolKit programs halt your program and 
bring up the ToolKit Interactive debugger. In those cases, an explanatory 
message is given. You can try to analyze the bug by examining the stack, 
the heap, registers, and so oa You can also try to ontinue program 
execution, by giving the Go c omm a nd, although the process or document may 
be damaged. It is generally better to halt your program and try to trace the 
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error with another process and document You can halt the program by using 
the Enter Lisabug command to reach Lisabug, and then giving a Go 
command. That c omman d causes a bus error. Type Go in response to the bus 
error, and the process is terminated. 

You can also use the ToolKit debugger to reach Lisabug, if you want access 
to the program on the assembler level The ToolKit debugger makes certain 
that you enter Lisabug while in user code; you cannot debug system code with 
either Lisabug or the ToolKit debugger. 

Whether you are using Lisabug or either of the ToolKit debuggers, the results 
of your actions show on the alternate screen. This display, maintained 
separately from the desktop, can be reached by holding down the Option key 
and pressing the Enter key in the numeric pad on the right side of the 
keyboard. To stop a ToolKit program and see the interactive debugging menu, 
press any key while the alternate screen is displayed. To return to the 
desktop, press Option/Enter again. 

A fully debugged ToolKit program normally is linked with a version of the 
ToolKit that has no debugging facllites. In order to use the ToolKit 
debuggers, you must link with the debugging version of the ToolKit The 
debugging version slows your application down by 20% to 40%, 

Lisabug also is only available in development versions of the Lisa system. 

52 The Pulldown Debug Menu 

The ToolKit pulldown debug menu allows you to check that your application is 
running correctly in certain respects. It does not give you any information 
about fatal errors, computational errors, or the state of fields and objects. It 
does, however, let you enable range checking on list accesses. You can also 
enable checks on objects in the heap, to identify objects that have no 
ref e rences and should be freed. Additionally, functions in this menu print out 
information about the process as a whole, about the document and about 
events as they occur. 

In all cases, the information is printed on the alternate screen. You can 
display the alternate screen at any time by holding down an Option key and 
pressing the Enter key that appears on the numeric keypad on the right side 
of the keyboard. Press Option/Enter again to return to the main screen. 

Here is a list of the com ma -id s in the pulldown menu, along with a brief 
description of each. More detail about each c omma nd is given in the 
subsections that follow. Four c ommand s are flags that are turned on when 
you select them. They remain in effect until you select them again. When 
they are in effect they are checked off in the menu The other c om ma nd s 
print information on the alternate screen each tim* the command is chosen. 

• Report Every Event prints brief information about every event It slows 
your program subtly. Disable this function by choosing it a second time. 
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• Count Heaps alter Commands prints the number of objects In each heap 
every time any command is given. This also invokes the Report Garbage 
in Document Heap menu c ommand. It slows your program slightly. 
Disable this function by choosing it a second time. 

• Check List Indfces enables range checking on list indices. When an error 
is found, the application is halted and a message is printed on the 
alternate screen, it slows your program slightly. Disable this function by 
choosing it a second time. 

• Dump Process Qlobals prints the values of various important global 
variables. 

• Dump Active Document Prelude prints some information about the 
currently active document 

• Enable Experimental Features enables features of your application that you 
have defined to be provisional, and do not want to appear in 
demonstrations, or in intermediate versions of your application. Disable 
this function by choosing it a second time. 

•Report Garbage In Document Heap prints information about objects in the 
document heap to which their are no references. 

• Free Garbage In Doounent Heap frees ail objects in the document heap to 
which there are no refe r ences. 

• Edit Dialog allows you to edit a dialog box. if one is currently displayed. 
The changes you make are not saved at this time. 

• Stop Editing Dialog stops dialog box editing. 

S2A Report Every Event 

When this option Is checked off, the debugger prints brief information about 
every event Like all information printed by the ToolKlt debugger, this 
printout appears on the alternate screen. 

Any keyboard or mouse button use triggers a printout by this function. For 
example, when the application user presses the mouse button, that is 
considered an event Releasing the mouse button is another event Clicking 
the mouse button is two events: one when the button is pressed, and one when 
it is released. Pressina a key Is also an event Moving the mouse, however, 
is not an event Clicking in a different window causes a deactivate event 
and an activate event Instead of mouse events. Choosing a menu command is 
an event only in that it Involves a mouse button press and release event 

The event type Is printed out along with the tool name, the process ID, the 
"folder" identification (that is, whether the event occured In a clipboard, 
dialog box, or window), and, If appropriate, the window title. Additional 
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information is printed for desktop events, including the kind of event, the 
password and the document prefix. 

When this option is in effect,, it is checked of f in the debug menu. To disable 
this function, choose the menu item a second time. 

S22 Count Heaps after Command s 

When this option is checked off, the debugger prints the number of objects in 
each heap every time any command is given. Like all information printed out 
by the ToolKit debugger, this printout appears on the alternate screen. 

Note that only commands trigger the printout; simple mouse button presses do 
not Key presses are considered commands. In addition, many mouse actions 
(such as click and drag) are considered command s . All menu items are 
considered commands for the purposes of this function. 

This function is useful for checking that your program is not leaving 
unreferenced objects on the heap. The number of objects on the rrap should 
not grow unrestrictedly, unless objects are actually added to the program's 
data set You can use the Report Garbage In Doc u men t Heap function to find 
out if there actually are unreferenced objects on the heapi 

This function is also useful for generally checking the impact of commands on 
the heap. 

When this option is in effect it is checked off in the debug menu. To disable 
this function, choose the menu item a second time. 

5u23 Check List ftdtees 

When this option is checked off, the debugger performs a range check 
whenever a list is accessed. When an error is found, the application is halted 
and a message is printed on the alternate screen. 

When this option is not checked off, the effect of an out-of-range list access 
is unpredictable. Such an access attempt could store data outside the object 
and damage other objects or heap structures. 

Enabling range checking slows your application somewhat 

When this option is in effect it is checked off in the debug menu. To disable 
this function, choose the menu item a second time. 
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$2A Dump Process Globels 

When you choose this option, the debugger prints the values of various 
important global variables on the alternate screen. The variables whose 
values are printed are: 

actlveflndowIP currentOocuwent menuBar 

allovAbort currentilndov myProcessID 

boundDllpboard cursorShape ■yTool 

boundDocuRent defertlpdate process 

clickState doctlst toolfiene 

clipboard genCllpPlc toolPref ix 

closedBySuspend IdleTlme toolVolume 

closedDocument InBackground 

The debugger only prints the first eight characters of each name. 

These values are only printed once. To print the values again, choose the 
option again. 

See Chapter 6, Section S32, UABC Global variables for more information on 
these variables. 

S2S Dump Active Document Prelude 

When you choose this option, the debugger prints some information about the 
currently active document The values and types of the following variables 
are printed. 

password -- A key nuitoer used to Identify documents, 

version — The version sequence number of this application. 

country — From the phrase file. 

language —From the phrase file. 

preludeSize ~ The size of the document prelude, in bytes. 

docSize — The size of the document, in bytes. 

numSegments — The nwtoer of data segments in use. 

docOirectory — The docoirectory object for this document. 

These values are only printed once. To print the values again, choose the 
option again, only the docSize and numSegments values should change. 

SJZjS Enable Experimental Features 

When this option is checked off, features of your application that you have 
defined to be provisional are enabled. The ToolKlt toggles the global boolean 
variable fExperimentlng on the basis of this command. To implement 
experimental features, simply surround code dealing with those features with 
a test on (Experimenting. When you check off this item in the menu, that 
variable is TRUE, and your provisional code is executed. Because the debug 
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menus do not appear in non-debug versions of ToolKit program your 
experimental code can never be executed in non-debug versions of your 
program. 

When this option is in effect, it is checked of f in the debug menu. To disable 
this function, choose the menu item a second time. 

52.7 Report Garbage In Document Heap 

When you choose this option, the debugger prints information about objects in 
the document heap to which their are no references. The information printed 
consists of the object's handle and class-type. To determine what command 
caused the problem, free the garbage by using the Free Garbage in Document 
Heap option, and try out various application comman d s, invoke the Report 
Garbage in Document Heap option after each command 

52-8 Free Garbage in Document Heap 

When you choose this option, the debugger frees all objects in the document 
heap to which there are no references. The objects freed are the same ones 
that would be indicated by Report Garbage In Document Heap. 

This command only acts once. To free garbage later, choose the option again. 

52.9 Edit Dialog 

This function is only enabled when one of your application's dialog boxes is 
displayed and the current selection is in the dialog box When you choose 
this command, the dialog box is re-displayed so that each separate piece of 
the dialog has a surrounding box and a title bar. You can use the mouse to 
grab any of the title bars, and move the piece around within the dialog box 
A size icon for the whole dialog box is also displayed, and you can use that 
to grow or shrink the box 

You can change any of the text that appears in the dialog box 

You cannot add elements to the dialog box All elements must be defined 
when you create the dialog box See the documentation on dialog boxes (not 
covered in this manual) for more information. 

When you are done editing the dialog box, choose Stop Editing Dialog from 
the debug menu. The changes you made to the dialog box are stored with 
that document. 

52J.Q Stop Editing Dialog 

This function is only enabled when a dialog box is displayed, and you have 
chosen Edit Dialog. It stops dialog box editing. See subsection 52.10 Edit 
Dialog for more information. 
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53 The Interactive Debugger 

The ToolKIt interactive debugger allows you to stop your ToolKit program and 
access a menu of interactive debug functions. You can use the interactive 
debugger to" find out 

• What methods are called when. 

• The values of variables, objects, and fields. 

• The current sequence of routine calls, back to the main program. 

In addition, you can set breakpoints anywhere in the program or step through 
the program at any pace. 

You can reach the Interactive debugger by keying Option/Enter to display the 
alternate screen, and then pressing the space key. (You can actually press 
any key, but a key other than the space key is taken as a command.) Your 
application is halted, and the interactive debugger menu and prompt are 
displayed. Figure 6-1 shows a sample of the debugger menu and prompt. 

Alternately, you can insert an ABC8reeJc call in your program, which halts the 
program and starts the interactive debugger. You can also call EntOebugger. 
ABCBreak turns off the debugger flags from the menu, while EntOebugger 
does not 

Occasionally, an error in your program may cause the ToolKit to call 
ABC8reek. In that case, a message describing the type of error is displayed 
on the alternate screen along with the interactive debugger menu and prompt 
ABC8reak automatically switches the display to the alternate screen. 

The interactive debugger is also invoked when a breakpoint is reached. In 
that case, the alternate screen is automatically displayed. 

Switching to the alternate screen does not affect the operation of a running 
application, unless you purposely stop the program by typing a key. The 
program does not receive any events that occur when the alternate screen is 
displayed; the single exception is when the mouse button is depressed when 
you switch to the alternate screen, in that case, mouse move and mouse 
release events are given to the running application, (if you halt the program 
while the mouse button is pressed, however, further mouse events are ignored,} 

ine debugger acts on the Clascal method, procedure, and function level You 
can find out information about objects and methods. In particular, assuming 
you have used the BP and EP procedure calls to begin and end all your 
methods, you can find out what method is called when. 

One important detail of using the BP and EP procedures concerns the level 
you assign to each of your methods. BP takes a level parameter. When you 
trace the action of your program, you can give the watch comman d (the 
tracing command) a minimum level. Methods below that level are ignored ttf 
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the trace. Nothing in the ToolKlt enforces level conventions. However, the 
following conventions are observed by the ToolKlt and the sample programs, 
and are recommended: 

• 1, 2, and 3 are low level ToolKlt routines. 

• 4, 5, and 6 are somewhat higher level ToolKlt routines. 

• 7 and 8 are major ToolKlt routines. 

• 9, 10, and 11 are building block routines. 

• 12 and higher are application routines. 

You can also set levels in and trace the action of procedures and functions 
that are not methods. Use BP and EP in the same way you do with methods. 
Note that, in general, procedures and function in the ToolKlt that are not 
methods do not call BP and EP, and, therefore, do not show up in traces, and 
cannot be traced. However, there is nothing stopping you from using BP and 
EP in your non-method procedures and functions. 

Here is a brief list of the functions in the menu. Tney are described in more 
detail in the subsections that follow. 

• Breakpoint allows you to set breakpoints on the entrance and exit of a 
method, procedure, or function that has BP and EP calls, in addition, you 
can set a breakpoint on any reference to an object of some class. Note 
that Llsabug has a spearate breakpoint capability that can set a 
breakpoint at any instruction in memory. 

• clearBreakpoints removes breakpoints set with the ToolKlt debugger. 
(Lisabug breakpoints are not affected.) 

• Debugstatus prints the current watch level and watch count and also lists 
the current ToolKlt debugger breakpoints, 

• EnterUsabug brings you immediately into Lisabug, making certain that the 
application's code (and not system code) is running. 

• Go continues your program's execution. 

• Prompt turns the interactive menu display on or off. It does not otherwise 
affect the operation of the debugger or your program. 

• StaokCrawl shows the call sequence currently in effect, all the way back 
to your main program. It is similar to the SC command is Lisabug. 

• FrameOump prints out information about one of the stack frames displayed 
by StaokCrawL 

• mspectObJect prints Information about any Clascal object currently used 
by your program. 

• HeapOump shows you the objects in the heaps. 
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• Memory Dump displays a portion of memory. This function works like 
tisabug's DM command. See the debugger chapter of the Workshop 
manual for more information. 

• LeveisToWatch sets the minimum level routine that is printed when you 
use the watch c ommand to trace your program 

• OutputTo directs a copy of trie interactive debugger's output to a file or 
to a printer, in addition to the output on the alternate screen. Anything 
you type on the alternate screen is also printed. 

• watch displays the names of routines that contain BP and EP calls as they 
begin and end. This command can also be used to step through the 
program. 

In all cases, you can invoke the command by giving the first letter of the 
command name in response to the interactive debugger prompt You can type 
the whole command name if you want — everything after the first letter is 
ignored until a space or a <RETURN> is reached. Some commands take 
optional command line parameters. In all of those cases, the debugger will 
prompt you for any parameters it needs that you do not give. 

53.1 Breakpoint 

this command allows you to set breakpoints on the entrance and exit of a 
method, procedure, or function, in addition, you can set a breakpoint on any 
class, or to any method of a given class regardless of the method's name. 

Mp to 10 breakpoints can be set in any one process at one time. 

Breakpoints are attached to the process, not to the document Therefore, if 
you open a new document that uses the same process as one where you 
previously set breakpoints, the breakpoints operate when that document is 
processed. 

you give the Breakpoint command by typing at least a B on the alternate 
screen in response to the interactive debugger prompt (You can type any 
amount of the word breakpoint that you want — as long as you give the B.) 
Then type <RETURN>. 

When you invoke this command, the debugger prompts you for two pieces of 
information -- a class and a method name. You can give botfu or either 
alone. 

You are first prompted with the message 

Class? 

You can supply a class-type (only the first eight characters are significant), 
or you can ignore the message and simply type <RETURN>. 

You are then prompted with the message 

Method? 
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You can supply a method procedure, or function name (only the first eight 
characters are significant), or you can Ignore the message and simply type 
<RETURN>.. 

If you give a period after the class name In response to the first prompt, you 
are not asked for a method name. 

Depending on the responses you gave to the prompts, there are four 
possibility to what kind of breakpoint is set 

• If you gave a class-type and no method, procedure, or function name, the 
breakpoint occurs on any call to a method defined by that class-type. 
Breakpoints are not set on calls to methods defined by an ancestor or 
descendant of that class-type, even if the call is made through a 
class-referenc e of the given class-type. 

• If you gave a method, procedure, or function name with no class-type, the 
breakpoint occurs on the entry and exit to any routine with that name. 
The breakpoint occurs whether or not the routine Is a method or a global 
or local procedure or function, and regardless of the level of the routine. 

•If you gave a class-type and a method name, the breakpoint occurs only 
on the entry and exit of the given method of the specifies class type, 
regardless of the class of the object ref er ence d. 

• If you gave neither, no breakpoint is set 

If you want you can give the breakpoint on the command line, separated from 
the Breakpoint command by one or more spaces. You can give the class-type 
and method name, in the form 

class>4ethod 

or you can give the class-type alone, in which case you are prompted for a 
method name. Alternately, you can give the class-type and a period (.), in 
which case you are not prompted for the method name. You can also give 
the method procedure, or function name alone, but it must be preceded by a 
period Q, even if the routine is not a method or the debugger will mistake it 
for a class-type. 



For a breakpoint to occur, the routine must call the BP and EP procedures. 
Note that the debugger does not check if 
exists, or if the routine calls BP and BP. 



Note that the debugger does not check if a routine with the given name 
« routine 



A breakpoint can be set on a routine that is swapped in or out On Lisabug, a 
breakpoint can only be set on a routine that is swapped la) 

Execution slows significantly when breakpoints are set 

To see what breakpoints are set use the DebugStatus command. 
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532 OearBrea k points 

This command removes breakpoints set with the ToolKlt debugger. Lisabug 
breakpoints can not be changed with this command. 

You can remove one breakpoint at a time, or you can remove all breakpoints 
at once. 

To remove all breakpoints, type ALU either on the com m and line, separated 
from the OearBreakpoints com m and by at least one space, or in response to 
the prompt that appears after you give the OearBreakpoints command. 

To remove a single breakpoint, type the sequence number of the breakpoint, 
either on the command line, separated from the OearBreakpoints command by 
at least one space, or in response to the prompt that appears after you give 
the OearBreakpoints command. 

The breakpoint sequence numbers appear in the display produced by the 
OebugStatus command. 

533 OebugStatus 

This command prints the current watch level and watch count and also lists 
the current ToolKlt debugger breakpoints. See the Level command for an 
explanation of watch level; see the Watch c ommand for an explanation of 
watch count. 

The breakpoints appear in the following format; 

1: class .method 
2: class .method 



rt class .method 

n is the largest number of breakpoints set at any one time in that particular 
process, up to a maximum of la If a breakpoint is set on a class-type (that 
is, without a method name) the method space is blank, although the period (.) 
still appears. If a breakpoint is set on a method, procedure, or function name 
(that is, without a class-type) the class space is blank. Note that the period 
always appears, even when the breakpoint is set on a procedure or function 
that is not a method. 

The sequence numbers that appear on the left are used in the 
OearBreakpoints command. When you delete a breakpoint, the sequence 
numbers of the other breakpoints are not changed The next breakjpoint set 
uses the lowest open sequence number. 
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53A EnterUsadug 

When you give this command the ToolKit delxigger brings you immediately 
Into Lisabug. You can then use Lisabug in the normal way. 

To get back to the ToolKit debugger, type G in Lisabug. Your program does 
not start running. The interactive debugger menu is immediately displayed. 

"mere are a few special features of Lisabug when used with ToolKit 
applications. See the Lisabug documentation in the workshop manual for more 
information. 

535 FrameDump 

This command prints out infomation about one of the stack frames. It 
prompts for a number. Give it the number appearing after the # sign in the 
StackCrawl output 

The information given Includes the section of memory containing SELF, and a 
range of memory containing local variables, and a range of memory containing 
the parameters for the call 

53* GO 

This co m mand continues your program's execution from where it entered the 
debugger. The normal office system screen is automatically displayed. 

53.7 HeapDump 

This command shows you the contents of the process, document, and clipboard 
heaps. 

If you type H alone to invoke this c ommand, you are prompted for several 
options. Alternately, you can type H classtype <RE*njRN>. In that case, only 
objects on the document heap of the specified class and its d esce n da nt 
classes are shown, and no prompts appear. 

53« mspectobject 

This command prints detailed information about any Clascal object that 
currently exists on your document or process heaps. Give the hexadecimal 
value for the object's handle, with or without the preceding 1 Here is a 
sample of output from this comman d . 

TSflflOBf C «t«rtUt: Utoct * [(0,0), («1, 555)] ; vim: Vfim « HMftftBI - ttOOMfttC 
; pml: TPwtl - 1MB. — tMMMM ; elioNUH: tMnt • (212,lli) ; pvintftan: 
TPrintfU s TITDPUM — iMMMtt ; Mk: INTEGER = M ; «Hm» INTEGER » it • 
RtaExttn: Utact > [(M),(S0,50)] ; i*liaU: IO0LEM * THE ; itfkditfi: MULE* * 
TUBE ; *mUMU TUst « TUHttJS — iWdWill 1 



Note that the exact format of the fields display depends on how you 
Implement the Fields method fdr this class. If you do not Implement a Fields 
method for a subclass that you define, you will not be able to see the 
contents of any field that your subclass added. 
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53.9 LevelsToWatch 

This command sets the minimum level routine that is printed when you use 
the watch command to trace your program. The level refers to the number 
given In the BP procedure call at the beginning of every method, procedure, 
and function that you wish to show up in the trace, or on which you wish to 
set breakpoints. 

When you execute this command, the debugger prompts you for a level 
number. The number you give is the lowest level routine that appears in the 
watch trace. 

The can be set to any whole number from 1 to 9999. It is 1 by default Use 
the DebugStatus command to find the currently set watch level. 

5A10 MemoryDump 

This command works the same as the DM command in Lisabug. See the 
workshop documentation for more information. 

53.11 OutputTo 

This command is used to direct a copy of the interactive debugger's output to 
a file or to a printer, in addition to the output on the alternate screen. 

When you invoke this command, you are asked where you want to direct 
output to. Give the destination by identifying the device and if appropriate, 
giving a file name. Give the device and file names proceeded by a dash, Just 
as you do in the Workshop. 

For example/if you want to direct output to the printer, type -printer. If you 
want to send output to a file on a diskette in the upper drive, type 
-upper-filename. If you direct output to an existing file, you destroy the 
current contents of the file. If the file does not exist, the debugger creates 
the file. If you want to examine the file in the workshop editor, it must have 
a name ending in .TEXT. 

The debugger output always shows on the alternate screen; OutputTo merely 
directs a duplicate to the given destination. 

Output can only go to the console and one additional destination. Naming a 
third destination closes the path to the second destination. 

You should always cancel the new output direction before going on to do 
something else. Otherwise, all other me s sages that go to the alternate screen 
are sent to the named destination, until you turn off the Lisa Other 
alternate screen me ssa ge s include the environments window display and the 
workshop command line. In addition, if you directed output to the printer, the 
printer is not available for any other use. 

Cancel the additional output direction by giving the OutputTo command a 
second time. You can type -Console, or simply type <RETURN>, as -Console 
is the default Turning off the Lisa always cancels the output redirection, 
and closes any open files. 
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53112 Prompt 

This command determines whether or not the Interactive debugger menu is 
displayed. It takes a Yes or No (Y or N) as a parameter. If you indicate Yes 
(either on the command line, separated from the Prompt command by at least 
one space, or in response to the prompt that appears if you do not specify Y 
or N) the menu is displayed. If you indicate No, the debugger prompt (-->) is 
displayed without showing the menu. 

The Prompt command does not otherwise affect the operation of the debugger 
or your program. 

5t*l3 RefsToObJect 

The RefsToObJect command displays the names of objects that refer to a 
given object RefsToObJect prompts you for an object handle. It then 
searches the document heap for all occurences of that handle. 

5JU4 StackCrawI 

This command displays* the current calling sequence in terms of stack 
frames. Here is a sample of a stack crawL 



Fnm t 
Fr«Mi 
Fnmf 
Fnmf 
Fnm f 
Fnm* 



1 a 

21 

4a 
5 a 
• a 



MW;/1 H-> IfWDCbSS .q WjBBHh 

0QF7MO0 TPWKESS.TMOKMt* 

0CF7AD1C TVDMU .DLEOMT* 

60F7MBC TAEcn.nusowT* 

MTIMU mMMM MCWCUCM* 

Wr/WPX IFW^cSS.URicVW 

O0F7MPt 1M0CESS.MM * 




Fnm t 7 a tNF7F*Z2 



HMVLE ♦*« 



53.15 Tally & Time 

The Tally & Time command allows you to measure the performance of your 
program. 

When you first invoke the command you are asked if you want to continue 
execution and measure performance. If you answer no, the c omman d is 
cancelled. If you answer yes, your application begins running, and the ToolKit 
records information on the methods and segments used. Every entry into a 
routine that begins with a BP call is recorded, and the time until the 
following EP is recorded. 

When you next enter the debugger On any manner except through A8C8reakX 
you are asked if you want to see performace measurements. If you respond 
no, you are asked if you want to zero the tallies and times. If you answer 
yes, all tally and time records are removed, and you are ready to start with a 
clean slate. If you answer no, any further performance measurments are 
added to the measurements up to that point 

Finally, you are asked if you want to continue performance measurement 
Once again, if you answer yes, your program starts Immediately. The only 
way to see the debugger menu is to answer no. In that case the menu is 
displayed. Note that in order to continue measuring performance, you must 
restart your program through the Tally & Time comman d . 



5-15 



Use ToolKlt Reference Manual ToolKft Debugger 

To see trie performance data, answer yes when you are asked if you want to 
see performance measurements. When you have such measurements recorded 
(that is, as long as you ran your program through the TaUy & Time command 
and did not zero the tallies and times) you are asked If you want to see the 
results whenever you Invoke the Tally & Time command, or when you Invoke 
the debugger having run the program through Tally & Time. 

When you ask to see the performance measurements, you are given some 
general information, and then a chart of segment usage. You are then asked 
if you want to see the procedure statistics. Note that these statistics 
actually show all routines containing BP and "EP calls, whether they are 
procedures or functions. Next, you are asked if you want to see a list of 
procedures that were and those that weren't called in a particular segment 
The "procedures that weren't called" once again include functions, and 
actually show all rotuines that do not contain BP and EP calls, in addition to 
routines that were not called. 

You can stop any listing at any time by hitting a key on the keyboard In 
that case, the previous question Is repeated. 

To skip a question and go to the next one, type a <RETURN>. 

53.16 watch 

The watch command displays the names of routines that begin with BP, end 
with EP, and have level numbers greater than or equal to the current watch 
level as they begin and end. This command can also be used to step through 
the program. 
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6.1 About this Chapter 

The ToolKit uses a number of predefined data types and global variables, 
procedures, and functions. Those that are of v interest or use to programmers 
using the ToolKit are documented in this chapter. 

The ToolKit uses a number of libraries that are not available to the general 
programming public. A few of the items in this chapter depend on definitions 
in these secret libraries. In addition, a few of the items depend on 
definitions in SYSCALL, the unit that defines the operating system used on 
the Lisa you should never need to deal directly with either the secret 
libraries or SYSCALL. SYSCALL is documented in the Operating System 
Reference Manual for toe Lisa 

62. Data Types 

The ToolKit contains a large number of type definitions. The definitions of 
class types are described in the class reference sheets in Part II of this 
manual. This section describes data types used in those class definitions. 
Refer to these pages when you encounter a data type that is not a class. 
The types defined in UABC begin with the letter T. 

&Z1 UObJect Data Types 

The data types in this subsection are defined in UObJect 

The following five types are aliases for commonly used types. 

Ptr - "LONGNT; 
ProcPtr - Ptr; 
Hantfle - "Ptr; 
S8 - STRINGftfc 
S255 - STRING[255]; 

The following data types are used in many places throughout the ToolKit. 

TFilePath - S255; This corresponds to Pathname in SYSCALL. 

TFilePart - STRINGp2l; This defines the length of each level in a 

pathname; corresponds to e_narne in SYSCALL. 

TPassword - TFilePart; 

THeap - Ptr; A pointer to a heap. Given to NewObJect when 

defining a new object 

TClass - Ptr; A pointer for a class. THECLASS, given a 

parameter to NewObJect when defining a new 
object, has a value of this type. 

Byte - -128-127; A signed, eight-bit value. 
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TPStrlng - *S255; 
TpINTEQER - "INTEGER; 
HJLONGBNT - "LONGINT; 
TAuthorName - STRNGpzt 
TClassName - STRBsEftt 
TOouecHeader - RECORD 

classPtr. TClass; 
Size LONGaNT; 



N\ argument of unitAuthor and ClassAuthor. 

A string for holding a class name. 

An alias for TOdUecUcn", which can be used 
for faster access to collections. 



END; 
TFastString 



The number of real elements., not counting 

the hole. 
dynStart INTEGER; The number of bytes from the classPti to 

the dynamic data; MAXBMT if none are 

allowed. 
holeStart: INTEGER; - at the beginning, size - at the end; 

hWONT - none allowed. 
holeSize: INTEGER; Measured in MemberBytes units. 
holeStcfc INTEGER; If the holeSize goes to 0, this is how much 

to grow the collection by. 



RECORD 



N\ alias for a TString 
faster access to strings, 
header. TOouecHeader; 

CTt PACKED /TOAY(l-3Z74(q OF OVSR; 
END; 

TPFAstString - "TFastString; 

THFastString - "TPFastString; 

TAnayHeader- RECORD 



which can be used for 



classPtn TClass; 
SiZB: LONGINT; 



N\ alias for TAnay , which can be used for 
faster access to arrays. 



The number of real elements, not counting 

the hole. 
dynstart: INTEGER; The number of bytes from the classPtr to 

the dynamic datau MAXMT if none are 

allowed. 
holeStart: INTEGER; - at the beginning, size - at the end; 

MAXB^rr - none allowed. 
holeSize: IMTEGER; Measured in MemberBytes units. 
hoteStdh INTEGER; This is how much to grow the collection by 

if the holeSize goes to a 
IBCOTdBytes: IMTEGER; 
END; 

TScanDirectlon - (scanForwant scanBackwanfi; 
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622 LTOC Data Types 

Hie following data types are defined in UABC. 

TDiResponse - (cOADcept, olDismissDlalaJBox, QlGiveToMalnWJndow, olRefuset 
Defines the response given when the user clicks in the main window or in the 
menu bar, or types when a dialog box is displayed. 

TEnumAWlities - (aBar, aScrolL aSpMJ; 

TAMllties - SET OF TEnum/¥rilities; Defines .whether or not there is a scroll 
bar on the side of a panel and if there is, whether or not there are icons for 
scrolling and splitting. 

TUmtsFromEdge - (pixelsFromEdge, percentFromEdgefc Used to define 
parameters for some TPanel methods. 

TAiertArg - 1_5; Used to define parameters for some TProcess methods. 

TAlertCounter - 6.9; used to define parameters for some TProcess methods. 

T AUgrinent - (aLeft aRlgfit aCenter, aXBtlf y)t 

TPageAUgnment - (aTopLeft* aTopCenter, aTopRio^C aBottomLefC 
aBottornCenter, aBottomRigjitJt 

TClickState - Defines a record that contains information about the 

most recent mouse click. 
RECORD 

where: Point; The window-relative point where the pointer was 

located, 
whert LONQDMT; The time in hundredths of a second from last 
boot when the mouse button was last clicked. 
clickCount: INTEGER; The number of times the mouse button 

was pressed in the period set by the 
user through preferences. 
fSWft, fOptioa f PfQle: BOOLEW; Whether these buttons were 

held down while the mouse 
button was clicked 
END; 

TCmdNumber - INTEGER; Defines a c o mm and number. 

TCmdPhase - (doPhase, undoPhase, redoPr»sek Dennes the command phase 
given to comman d Perfona 

TCuisarNumber - INTEGER; 

TEnumlcons - QSkewer, lScroilBack, IFUpBacK, IGrayA, iTnumb, lGrayB, 
IFlipFwd, iScroUFwdfc Used internally to define scroll bar icons. 

TMousePhase - (mPiess, mMove, mReteasek Used internally for mouse 
tracking. 
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TRevelatlon ? (revealNone, revealSome, revealAilk Defines how much of the 
selected objects should be scrolled into the view if the user tries to operate 
on them 

TPiReserve - ARRAY [0.127] OF Byte; Defines an array of printer 
information. 

TPrelude - Defines a prelude stored at the beginning of every 

document's heap. 
RECORD 

password: (21 INTEGER; Presently unused. 

version: J2j INTEGER; Presently always L 

country: g BsTTEGER; From phrase file. 

language: g BsTTEGER; From phrase file. 

preludeSlze: (2| IMTEQER; Contains SEZEOF (TPrelude). 

mused: 16) ARRAY [05] OF Byte; 

printPref: (128) TPiReserve; Format for printer information. 

docSize: W L0N6INT; Number of bytes in document 

nunSegments: ti INTEGER; Number of 128K files in document. 

docDirectory. ft) TDocDirectoiy; Root object in document 

heap. 
END; 

TPPrelude - * TPrelude; 

TSBoxID - LONGQNT; An alias for a secret library type. 

TWindowlD - LONGONT; Ail alias for a secret library type. 

63 Global variables 

The ToolKit defines a number of global variables. Unlike variables which 
exist as fields of classes, these variables can be accessed from any part of an 
application that USES the ToolKit 

If an R appears before the variable name in the following lists, you might 
sensibly want your to application read the value of the variable. If a w 
appears before the variable name, you can alter the value of the variable. 

63.1 UObject Global varlattes 

The following variables are defined in UObJect 

R amDyintj BOOLEAN; If TRUE, this process is terminating. 

fChecklndtoes: BOOLEAN; If TRUE, list indices are checked. 
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RW fDebucpeoursion: BOOLEAN; TRUE if you want want to inhibit tracing; you 

must save and restore its value; normally this 
is needed only if you override the Debug 
method. If you do that, save the old value of 
this variable in your Debug method Then set 
the value to TRUE to inhibit tracing. Finally, 
before you method completes, restore the old 
value. 



R islnitiailzed: BOOLE/*fc 

w keyPresUmit- INTEGER; 

matnDsRemum: INTEGER; 

R meinHeap: THeep; 
malnLdsn: INTEGER; 
R onDesktOp: BOOLEW; 



if TRUE, the application is initialized, and it 
cannot tell the desktop manager that inltFailed 
any more. 

How often to call Keypress from the debugger 
to check for user interrupt 

The file system reference number (refnum) of 
the process data segment 

The heap of the process. 

The ldsn of the process data segment 

If TRUE, the application is installed in the 
desktop. Nearly always true if UABC is used, 
because programs using UABC usually run on 
the desktop. 

wmlslnitiallzed: BOOLEAN if TRUE, the window manager is open. 

632 uabc Global variables 

TTte following global variables are defined In UABC for use by the ToolKit 
They are set in TProcessDommence, and can be considered fields of the 
process. In particular, changes to these variables affect all documents using 
that process. 

You can examine the values of any of these variables, but only the variables 
whose name is preceded by an R are ejected to be meaningful to you. 

You should not change the value of any of them, except for a few that are 
preceded by a w. 

actlveWIndowlDt TWlndowt); The window manager ID of this process's active 

document window, or (zerol if there is no 
active document 



aBowAbort- BOOLEAN; 



R amPrimOngp BOOLEAN 



If TRUE, aborts of the process are allowed. If 
F^SE, processj^ibort requests always return 
FALSE. 

TRUE if this process is presently printing 
rather than drawing. 
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autoBreakPen: 



PenState; 



WlrtcOffCenUSBCs: LONGONT; 
MinkOriCentlSecs: LONGBNT; 
botncClipboanfc TClipboarcfc 
bcuncDocument: TDocManager; 



cancelString; STRlMG(20t 
R clickState: TCllckState; 



R clipboard: TCUptoant* 
cllpPrlntPref: TPrReserve; 
closeoBySuspend: BOOLEAN: 

closedDoctinent: TDocManager; 
ameiNumberStyle: TTypeStyle; 

cunentDoament- TDocManager; 



R ctorrentWindow: TWlndow; 



cursorShape: TCursorNumber; 



The pen state to use to draw automatic page 
breaks. 

The time in hundredths of a second that the 
Insertion point is off. 

The time in hundredths of a second that the 
insertion point is on. 

The clipboard whose data segment is bound, or 
Nft_ if no clipboard is presently bound. 

The document whose data segment is bound, or 
ML. Usually the active document, if there is 
one, although applications can temporally bind 
inactive documents. 

The word "Cancel" for use in buttons, given in 
the current language. 

The place where the mouse was last clicked, 
the number of times it was clicked, and 
whether the shift key was pressed, the option 
key was pressed, and the Apple key was 
pressed 

The clipboard document manager. 

The print-preference for the clipboard. 

If TRUE, clcsedDoainent was just suspended 
and not saved. 

If not NIL* this document was Just closed 

The type style used for page numbers in page 
preview mode. 

The active document if the process is running 
in foreground. If the process is running in 
bac3kpjound, this contains the docManager that 
Is managing the background document. 
Otherwise contains NL. 

The window for the current document 
(aerentDocuTientwindow), or NB_ if there is no 
current document or there is no window 
because the process is running in the 
background. 

TheatfrentaffscT shape, as recorded by 
TProce$s£hangeCursor. 
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w aefferupdate: BOOLE** 



If TRUE, display update is deferred while the 
user is typing until some non-typing event 
occurs. 



docUst: TUst {OF TO ocManageifc The open docManagers using this process, 

R eventTime: LONGDMT; The time of the most recent event, in 

hundredths of a second from system boot 



R eventType: INTEGER; 



R fExperimenting: BOOLEAN; 



fCountHeap: BOOLEAN; 



R genCUpPte: BOOLE** 



The type number of the most recent event 
The available types are: 

- nil event 

1 - mouse button down 

2 - mouse button up 

3 - key down 

4 - folder activate 

5 - folder deactivate 

6 - folder update 

7 - folder moved 

8 - desktop manager event 

9 - abort event 

10 - died event 

11 - private 

12 - private 

13 - private 

If TRUE, enable experimental functions. This 
value is changed by choosing ENABLE 
EXPERIMENTAL FUNCTIONS from the debug 
menu You implement e^erimental functions 
by testing this value to see if the experimental 
sections should be executed. 

If TRUE and IFC fCheckHeap, count objects 
once per command. This value is changed by 
choosing Check and Count Heaps after 
Commands from the debug menu 

If TRUE, this process is now drawing the 
universal Graph component of the clipboard. 



R hi^lLevel: ARRAY [BOOLE**] OF TH&manslt; 

If TRUE, the value is the higWi^ting transition 
from not active to active (hOffToOn); if FfiUSE, 
the value is the higptfigptlng transition from 
active to not active (hOnToDim). 
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R M£)Toggle: ARRAY {BOOLEAN] OF THI^TransIt; 

If TRUE, the value is the higpligpiting transition 
from not selected to selected (hOffToOn). if 
FALSE, the value is the hio^lghting transition 
from selected to not selected (honToOfft 

The time since the application finished 
processing the last user input, in hundredths of 
a second. •* ' * • 



R kfieTime: LONGINT; 



RW inBackgroundt BOOLE/Ysfc 

limboPert PenState; 

manualBreakPert PenState; 

marginPattern: LPattem; 

R menuBan TMenuBar; 
myProcesslDc LONGBMT; 
myTOOl: LONGINT; 
normalPert PenState; 
okStrinp; STRDMG[2flt 

phraseFile: TFileScamer; 
R process: TProcess; 

R screenRk?)tEdge: INTEGER; 

scrollRgt RgnHandle; 

R stdMargins: LRecf 



TRUE if the process is allowed to run in the 
background. The program must set this value. 

The pen state used to fill limbo area in 
paginated view. 

The pen state used to draw manual page 
breaks. 

The pen pattern used to fill margins in 
paginated view. 

The menuBar object for this document 

The OS process ID for this process object 

The tool number of this application. 

The pen state resulting from PenNormaL 

The word for "OK" for use in buttons, in the 
current language. 

The fU e scanrte r for the main phrase file. 

The process object presently being used by this 
application. 

The horizontal size of the screen in pixels. 
720 for Lisa L0 and 2.0 screen 

The region that needs to be refreshed because 
of a scroll. 

The standard page margin size, in pixels. One 
inch on each side. 



suspendSuffbc A3RAY [UnaxSegments] OF STRDMGpl 

A suffix string (SSL SS2, 



theeodyPatt TBodyPacf 
theMaxginPad: TMarginPad; 



) for each data 
segment used by the document 

The bodyPad used for printing and paginated 
views. 

The marglnPad used for printing and paginated 
views. 



6-9 



Lisa ToalKlt Reference Manual 



Reference Information 



tOQlName: STRING[67); 
R toolPreflx TFilePath; 



R toorvtflume: TFilePath; 



wordDellmlters: STRBMG[67]; 



The name of this application as specified by 
the installTool program. 

The Desktop Manager and OS file prefix used 
for this application. Has the form (Tram). 

The name of the volume on which this 
application resides. Has the form -volume-. 

The delimiters of a word in the current 
language. These delimiters are defined in the 
phrase file, as are ail language-specific values, 
and Indicate what character sequences define 
the beginning and end of a word. 

6w4 Global Procedures and Functions 

The ToolKlt defines a number of procedures and functions that are not 
methods of any class, and can be called from any unit that USES the ToolKlt 

6.4.1 UObJert Gtobal Procedures and Functions 

The following are the global procedures and functions that can be used in 
application programs and are defined in UObJect 

PROCEDURE intToStr (Hit: INTEGER; Stn TPStltagfc 
PROCEDURE UTItToStr flnt: LONG3NT; Stn TPstrJn$ 

These functions return a string containing the integer int. IntToStr 
takes an integer operand; UntToStr takes a long integer operand. 

PROCEDURE SpHtFitePath (fullPath, ItsCatalog, ItsFUePart: TFUePatrfe 

Given ftfflPath returns ItsCatalog and ItsFUePart Levels in the 
Lisa's tree-structures file system are separated by dashes. This 
procedure searches backwards from the end of adlPatrt Everything 
after the last dash in fullPath is placed in ItsFUePart The rest of 
the string is placed In ItsCatalog. 

FUNCTION Mlrfl, * LONGBNT> LGNGONT; 

Returns the smaller of the two numbers. 

FUNCTION MB><L J: LONGINT} LONGINT; 

Returns the larger of the two numbers. 

PROCEDURE XfeiLeft(source, dest: Ptr; nBytes: MEGER); 

Moves bytes from memory from source to dest starting with the 
leftmost byte. 

PROCEDURE XferRi^wurce, dest: Ptr; nBytes: VfTEGER); 

Moves bytes from memory from source to dest starting with the 
rightmost byte. 

FUNCTION EQualBytesCsouroe, dest: Ptr; nBytes: 14TEGER> BOOLEAN; 

Returns TRUE if ail the bytes in source and destination have the 
same value. 



6-10 



Usa TooJKJt Reference Manual Reference Information 

FUNCTION Lint/VldUnt(L > LONGNT> LONGaNT; 

- Returns the logical AND of the two numbers. 

FUNCTION UntOfUnKL * LONGINT} LONG3NT; 

Returns the logical OR of the two numbers. 

FUNCTION UntXCMUntfl, * LONGINT> LONGBNT; 

Returns the logical exclusive OR of the two numbers. 

FUNCTION NewObJect(heap: THeap; itsClas* TClass> TObJect; 

Creates a new object of type ItsClass, of a size defined by 
ItsClass. 

FUNCTION NewpynObJect(heap: THeep; ItsClass: TClass; dynBytes: NTEGER): 

TObJect* 

Creates a new dynamic object of type TClass, of a size defined by 
ItsClass plus dynBytes. This is used to create dynamically 
allocated objects, such as arrays. 

PROCEDURE ResizeDynObjBCt(obJect: TObJect; rewTotSIBytes: INTEGER* 

Changes the size of a given dynamic object to the hew size. 
newTotalBytes must include the class size plus the size of the 
dynamic fart 

FUNCTION NewOiRecycledOb ject(heap: THeep; ItsClass: TClass; V/V* chainHeacfc 

TObJect* TObJect; 
Checks the given chainHeed to see if there are any objects to be 
recycled If there are, this procedure reuses the object so that 
new space does not have to be allocated. If there are no objects 
to be recycled NewObJect is called to get a new object This is 
used when many objects of a particular type are created and freed 
quickly. chainHead must be of the same type as ItsClass, and must 
also be on the same heap. 

PROCEDURE RecydeObtect(objBCt: TOb ject* V** chainHead: TObJectfc 

Adds the given object to the group stored by chainHead. This 
procedure is called in place of Free when you are creating and 
freeing objects of a particular type quickly. In that case, use this 
procedure in place of Free, and NewOrRecycledObjBct in place of 
NewObJect chainHead must be of the same class as the recycled 
objects, and must also be on the same heap. 

PROCEDURE Free (Object TObjBCtt 

Deallocates the heap space used by the given object All 
references to the object become invalid If the object is NIL 
(indicating it has alreaefing been freed), this procedure does nothing. 

FUNCTION SMperclass(class: TClass): TClass; 

Returns the class pointer for the superclass of the given class, or 
NIL. 
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FUNCTION ClassOescendsFrom(descendant ancestor. TCiassfc BOOLEAN 
' Returns TRUE If ancestor is an ancestor class for descendan t 

PROCEDURE NameOfClassCclass: TCiass; VAR className: TClassName); 

Gets the classname of the class using the given class pointer. 

FUNCTION SizeOfClassCclass: TClassJc INTEGER; 

Returns the size, in bytes, of an object of type class. 

The next 3 procedures can only be called from -a class-init block or a subroutine 
of a class-init block. 

PROCEDURE UrttAutrioi(cwnp^ TAutrioiName); 

Registers the company and author name for all classes defined in a 
unit This procedure must be called once in every unit 

PROCEDURE ClassAuthoi(cx»TTp8ny/>ndALithon TAuthorName; classAlias: 

TClassName); 
Overrides a registered company and author name, for use when you 
declare a methodless dummy of someone else's class for version 
conversion. 

PROCEDURE CiassVersionfltsVersion oldesUtCanReafc Byte); 

Used in releases past first release of your application This 
procedure is added to every class that requires data conversion, 

PROCEDURE ABCBreakfe S255; enCodR LONGING 

Stops the application. If the application was linked with the 
debugging version of the ToolKit, the debugger is invoked. 
Otherwise, a technical difficulties dialog box is displayed or, if 
called early in the application, the system may hang. This 
procedure should generally be surrounded with IFC compiler 
directives, so that non-debug versions of your program do not 
contain breaks. You can use ABCBreak calls in non-debug versions 
of your program. In that case, the program halts. 

PROCEDURE UntToHe^decNumben LONGDMT; tetfMumber. TPStringfc 
Converts a LONGDMT to a hexadecimal number. 

PROCEDURE EntDebuggeiQnputStr, enteiReasort $255); 

Invokes the ToolKit interactive debugger. The enteiReason string is 
displayed, inputstr is ignored. 

PROCEDURE DumpVaxftAtalatte: Ptr; name/WType: S255k 

Writes the value of a variable on the alternate screen. 

PROCEDURE WlStl(str. S295* 

Like the required Pascal function WRITE, but performs word wrap 
when necessary. (Warning: This routine may have bugs.) 
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PROCEDURE WlLrc 

Like the required Pascal function WRITELM but performs word 
wrap when necessary. Every time this is called the next line is 
Indented by the number of characters indicated by outpuundent an 
NTEGER global variable of uobject 

PROCEDURE WrObJobJect: TObjBCfc numLevels: INTEGER; memtoerTypeStr: S255)fc 
Like QbjB&Debug, but it formats using the outputlndent global 
variable to define the left margin: 

FUNCTION NewHeapCWV* error: BsTTEQER; heapstarl numBytes: LONGfflNT; 

numObjects: NTEGER): THeap; 

Creates a new heap. The ToolKit calls this for yoa You should 
never call this function. 

FUNCTION MakeOataSegment(VAR error,, dsReftunt INTEGER; flrstTryVotume, 

trenTtytttiume: TFUePaftrtfdsn, memBytes, 
(flskBytes: INTEGER* LONGINT; 

Creates a new data segment The ToolKit calls this for yoa 

You should never call this function 

PROCEDURE SetHeap(heap: THeepfc 
procedure QetHeap(V/« heap: THeapk 

These routines deal with the heap used by QuickDraw for regions. 
You can use these to but QuickDraw regions on other heaps. 

PROCEDURE MarkHeap(heap: THeap; mpAddress: LONGBsfT); 

PROCEDURE SweepHeap(heap: THeap; report- BOOLEAN 

These routines implement garbage collection. Tney are called by 
the functions in the debug menu that deal with garbage collection 
If report is TRUE, the garbage is reported and not freed. If report 
is FfiLSE, the carnage is freed and not reported. You should never 
call these routines directly; they are called when you choose 
commands from the debug menu 

procedure BP(MyTrac8Levetintegeri; 

Marks the beginning of a method or other routine for debugging 
purposes. You should begin all your methods with a call to this 
procedure, since the ToolKit debugger will otherwise ignor your 
methods. Also, see PROCEDURE EP. 

PROCEDURE EP; praoe entry from method and write SELF (unless create. 

Debug, FreeObject or Freel 
Marks the end of a method or other routine for debugging purposes. 
See PROCEDURE BP. 

procedure HexstiTcAJntOiexstrlnflp Tilling; var decNuritien longkt; var 

result: TOontftesult); 
Converts a hexadecimal string to a long integer, result tells 
something about the result and can be: cWallct cvNoNumder (null 
inputs cvBadMiTter (invalid character in input), or cvOverflow. 



6-13 



Use ToolKIt Reference Manual Reference Information 

PROCEDURE StiToUnt(stn TPString; VfiR decNumben LONGHT; VfiR result: 

TConvResulQ; 
Converts a string to a long integer, result tells something about 
the result and can be: cWtalia (JvNoNumber, cvBadNumber, or 
cvOverflow. 

PROCEDURE StrTomtfstr. TPString; VAR decNumben INTEGER; v/« result: 

TGorMtesulQ; 

Converts a string to an integer? result tells something about the 
result and can be: cWaUa ctfMoNumber, cvBadNumber, or 
cvOverflow. 

PROCEDURE TrimBlar*3(stn TPString); 

Removes leading and trailing blanks from str. 

function CharuppeiCasedtcrt CHtf$ CHfiR; 

Converts the character to its corresponding uppercase character. 

PROCEDURE StiUpperCasedCstn TPString; 

Converts the characters in the string to their corresponding 
uppercase characters. 

PROCEDURE LatestEnoKnewErron INTEGER; VAR previousError. INTEGER^ 

This Is used to handle error codes returned by multiple 
operations, so that you end up with the first error number or 
warning number (error code < 0) if there was no error. 

You should pass in the latest error as newError and the 
variable that is to be the final error code as previousError. 
Here is the actual code of LatestError: 

IF ((nenError > 0) AND (previousError <= 0) OR 
( ne w Ci r or < 0) AND (previousError = 0)) THEN 
previousError :* nenError; 

6A2 UfiBC Global Procedures and Functions 

The following are the global procedures and functions that can be used in 
application programs and are defined in UABC. 

FUNCTION TooiOflFUe (whOteName: SZ55)e LONGNT; 

Given the name of the toot this returns the tool number. When 
given a string of the form {Txxxjobi, returns xxx 

FUNCTION TODlOfProcess Cprocessld: LONGaNTJc LONGWT; 

Given an OS process ID, this returns the tool number using that 
process. 

The following routines are used to insert comments into the universal Graph of 
the clipboard so LisaDraw can understand it 
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PROCEDURE PteTextBegln (alignment TAUgnmentk 

PROCEDURE PIcTextEHtfc 

Tftese two routines surround a sequence of text drawing calls that 
should be considered one field in LlsaDraw. 

procedure PtoQrpBegln; 

PROCEDURE PtoQpEntf 

These two routines surround a sequence of drawing calls that should 
be grouped in LisaDraw. 
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Partn 
Class Reference Sheets 

1 About the Reference Sheets 

This part contains reference sheets for the classes in UABC, UDraw. and 
UODject Not all classes are included nor are all their methods; however, 
you do not need to know about any that are not included here. The reference 
sheets document methods, subclasses, superclasses, data fields and other 
relevant information for the classes. 

All of the classes and all of their methods can be found in the interface 
units, copies of which are given in the appendices. 

There is one reference sheet for each class. 

All reference sheets follow this format 

CLASS: TTWSClass 

superclass: TSuperciass 

DEFINED SUBCLASSES) TSUbClass(es) 

INHERITED DATA FIELDS: Data fields inherited from TSuperciass, and 

their significance. 

DATA FIELDS: Data fields defined by TThisClass. and their significance. 

t-CTHODS: Methods implemented by TThisClass or inherited from 

TSuperciass. divided into a number of explanatory catagories. 

FAILURE CONDITIONS Typical causes of failure of methods of 

TThisClassJf any. (See Section 1A) 

NOTES: Pertinent notes on TThisClass and its use. 

In these reference sheets, the following symbols are used: 

*»* to indicate classes that must be subclassed for use. 

R before a data field to Indicate that the contents of the data field 
can be sensibly read. 

W before a data field to indicate that the contents of the data field 
may be modified by the application. 

2 CREATE Methods 

Every class must have its own create method, in every case, the first two 
parameters of CREATE must be an object and a heap pointer. See Chapter 2. 
uobject for an explanation of the use of these two parameters. 
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3 "me Reference Sheets 

The remainder of this chapter is an alphabetical listing of the reference sheets. 

Each reference sheet begins on a new page. Please check the emanation of symbols 
above before reading the reference sheets. The sheets are in alphabetical order. 
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CLASS: TArea. 

SUPERCLASS: TObJect 

DEFINED SUBCLASSES: TBand 

TBranchAree (not documented) 

TPafl 

TPanel 

TWindow 

WHERITED DATA FIELDS: none 

DATA F1ELD& R lrmerRect- Rect; Window-relative bounds excluding 

borders. 
R outerRect Rect; Window-relative bounds including 

borders. 
RW parentBrancrt TBranchArea; The branchArea that Indicates the 

parent of this area 

IMPLEMENTED METHODS: 

cnUdWithPt <pt Point; chlldList: TUst; VAR nearestPt: Palnft TArea; 

pt is a point in window-relative coordinates. 
chlldList is a list of areas contained within this area 
nearestPt is the point in the returned area closest to pt 
The return value is one of the areas from childList 

TAreaChildWithPt first finds the point in areaimerRect closest to 
pt It then the compares the new point to the outerRects of all the 
areas In chlldList When it finds the area that contains the point, it 
finds the point in that area's imerRect that is closest to the point 
That value is returned as nearestPt The area containing nearestPt is 
the return value. 

Erase; 

TAreaErase erases the interior. This assumes the focus was set by 
calling Focus. 

Frame; DEFAULT; 

Overridden versions of Frame draw outlines, scroll bars outside the 
inner rectangle. TAreaFrame draws a one-pixel wide box around the 
area Frame assumes the focus was set by calling Focus. 

QetBorder (V/^ border. Rectt DEF/MJLT; 

border is the width of the border. 

GetBoider returns the widths of the border bars. Each of the fields 
of the Rect defines the width of the border on the corresponding 
side. The standard sizes returned by overridden versions of 
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QetBorder are: for windows, bands, penes: 1 all around; for panels: l 
oh leftnop, scrollBars on right/bottom. TAreaQetBorder returns a 
border that Is one-pixel wide on all sides. 

SetBmeiRect (newlnneiRect: Rectfc 

newlnneiRect is the area bounds excluding borders. 

TAreaSetlmerRect sets the inner rectangle of an area This method 
also resets the size of the outerRtect based on the border size given 
by QetBorder. 

SetOuteiRect (newOuteiRect Rectk 

newouterRect is the bounding box. 

TAreaS et O ut eiRect sets the outer rectangle to a new size. This 
method also resets the size of the InnerRect based on the border size 
given by QetBorder. 

ABSTRACT METHODS: 

DownAt (mousePt Point* BOOLEAN; ABSTRACT; 

mousePt is the place the mouse button was last pressed. 

TAreaDownAt does nothing; subclasses should implement DownAt so 
it returns TRUE if mousePt is in the area it is implemented for you 
by TWindow, TPane, TPad and TPanel the subclasses of TAiea that 
need it 

FOOUS; /«STRADT; 

TAreaFocus focuses the grafPort on this area Focus is an abstract 
method here, but is implemented by TWindow, TPane, and TPact 
subclasses of TArea 

Refresh (rActtons: TActtons; hWmansit: THigmansItk /«STRACT; 

r Actton s js what to do in the area from the set of TActtons: lErase, 
iFrarne, iBackground, iDraw. 

hJjptTtansIt is the change In highlighting in the area The standard 
choices are: hNone, hOffToDim, hOffToda hDlmToOn, hOlmToOff, 
MOnToOff, and hOnToDim. 

TAreaRefresh does nothing; subclasses should implement Refresh so 
it redraws any changed parts of the area It is implemented for you 
by TWindow, TPane, TPskt TMarglnPafll and TBodyPadl subclasses of 
TArea 

Resizelnside (newlnneiRect: Rectfc ABSTRACT; 

newlnneiRect is the area bounds e>ocluding borders. 

Resizelnside is intended to change the size of areaimerRect It 
should be implemented to do higher-level operations on the area 
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such as resizing areas contained within this area, and then call 
SELF^etmnerRect 

Resl2eOutside (newOuteiRect: Rectfc ABSTRACT; 

newOuterRect is the bounding box 

ResizeOutside is Intended to change the size of areaouterRect it 
should be implemented to do higher-level operations on the area 
such as resizing areas contained vftthin this area and then call 
SELF^etOuterRect 



NOTES: 



1. TArea implements area objects that are used to define areas on the screen 
in a general way. The areas may or may not have borders. TWindow, 
TPanet TPane, TPatt TBanfl, TBranchArea and TDialogBox are all 
descendents of TArea 

2. You never create a TArea object You always use some descendant of 
TArea 

3. You will not usually not subclass TArea 

4. You will subclass one descendant of this class, TWlndow. 

5. The boundaries of an area are set with the methods SetOuterRect and 
SetlmeiRect Do not change inneiRect or outerRect directly. 
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CLASS: TArray 

SUPERCLASS 



TCollection 



DEFINED SUBCLASSES: none 

1NHERTTED DATA FIELDS: R size: LONGEST; 



dynstart: INTEGER; 
holeStart: INTEGER; 



hOleSize: INTEGER; 
hefleStd: INTEGER; 



DATA FIELDS: R IBCOTdByteS: INTEGER; 
METHODS: 



"me number of real elements in 
this array, not counting the 
hole. This is a LONGINT for 
*the benefit of huge collections, 
such as remote data bases, it 
is always in the INTEGER range 
for instances of TArray. 
The number of bytes from the class 
pointer to the dynamic data area 
means hole at the beginning; 
value of size means hole at the 
end. 

The initial size of the hole, 
measured in number of members.- 
How much to grow the array by if 
the hcfleSize goes to a 
Bytes per record. 



CREATE (Object: TObJect; ttsheap: THeap; WtialSlaok: INTEGER); 
bytesPeiRecord: INTEGER): TAnay; 

lnltialSlack is the size of the initial hole, m member-sized units. 
bytesPeiRecord is the number of bytes per record you wish the 
array to have. bytesPeiRecord must be an even number. 
^H2E£ft\reconrrype) is often used. 

TAnay.CREATE creates an empty array on ItsHeap that has 
bytesPeiRecord bytes per record (array jecorcByte&- 
bytesPerReoarcQ. inittaiSlack is a hole for array members, 
expressed as the number of members the hole could hold, if 
irttialSlack is greater than 0, the insert methods can be used to 
initialize the list without allocating any additional space. 

At Cb LONGBMT> PtT; DEFAULT; 

1 is an ordinal position in the array. 

The return value is an address for the element 

At returns the address of the element at the given position in the 
array. Because the address is in relocatable storage, it is valid 
only until the next time the heap is compacted. For that reason, 
GetAt is preferable. 
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This method is used for a simple subscripted fetch, instead of 
using 

*- ardAnayPt 

as you would to fetch element i from the Pascal fiPSWf 
ordArray, you write 

*- TpRecord(myArrayjOktp"; 

to fetch element 1 from the TAnay myArray. 

Debug (numLevels: INTEGER; memberTypeStn S255); OVERRIDE; 

numLevels is the number of levels of detail printed. 
memberTypeStr indicates how the array elements should be 
treated. This value is a data type; the debugger prints out the 
values of the elements as if they were of this type. 

Debug is called by the ToolKlt debugger to print details about 
this array. numLevels determines how many levels of detail are 
printed When numLevels equals: 

(zero), the debugger prints just the class of array; 

1, the debugger also prints size of array; 

2, the debugger also prints a compacted list of member classes 

greater than or equal to 3, the debugger also prints class, size, 
and calls Debug(ntinLevels-l) on members of the array. 

DB1A11; DEFAULT; 

DeiAU deletes all the elements of an array. The array Itself is 
not deleted, may-slze becomes 0. There is a hole of size 
array.hoieSlze. 

Each (PROCEDURE DOTOObjBC^^^ 

DoToObject is a PROCEDURE that takes a pointer as its 
argument. 

Each applies the given PROCEDURE to each element in the array. 
For example: 

my Array£ach (TaUy)t 

is equivalent to: 

FOR 1- 1 TO myAiray^ize DO 
Tally (nyftray.AtQ& 
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DeiAt Q: LONGINT); DEFAULT; 

i is an ordinal position in the array. 

DelAt deletes the element at position fc elements after i are 
renumoered to fill in the empty space. 

DelFirst; 

DeiFlrst deletes the element at tte beginning of the array; 
elements after the first are renumbered to fill in the empty 
space. This is equivalent to array.DelAt(U 

DelLast; 

DelLast deletes the element at the end of the array. This is 
equivalent to DelAt(array.size> 

DelManyAt (J: LONGONT; hOWMany: LONGaNT); DEFAULT; 

1 is an ordinal position in the array. 

howMany indicates the number of array elements to be deleted. 

DelManyAt deletes a number of elements from the array. The 
first deleted element is at position fc elements after i+howMeny 
are renumbered to fill in the empty space. 

First Ptr; 

The return value is a pointer to a record whose size is 
array jrecordBytes. 

First returns a pointer to the first element in the array. This is 
equivalent to array.At(l). 

QetAt (L- LONGWT; pElement: Ptrfc 

1 is an ordinal position in the array. 
pElement is an address for the element 

QetAt returns the address of the element at the given position in 
the array. It is similar to At except that the syntax of the call 
is 

my Any .QetAt (t •xfc 

instead of 

X?- rnyArray.AtQr; 

QetAt is safer, because your program does not deal with a pointer 
to relocatable storage. 

InsAt 0: LONQDMT; pRecoid: Ptlfc DEFAULT; 

1 is an ordinal position in the anay. 

pReoord is a pointer to a record whose size is arrayjecordBytes. 
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InsAt Inserts an element in the array. The newly Inserted 
element occupies position L 

insFirst (pRecorcfc Ptrfc 

pRecord is a pointer to a record whose size is aarrayjecoroBytes. 

msFirst inserts an element at the beginning of the array. The 
new element occupies the first position in the array. This is 
equivalent to arrayinsAt(l* pRecdrd). 

InsLast (pRecord: Ptrfc 

pRecord is a pointer to a record whose size is aarrayjecoroBytes. 

InsLast Inserts an element at the end of the array. The new 
element occupies the last position in the array. This is equivalent 
to arrayJnsAt(anay.Slze*l, pRecortO. 

Last Ptr; 

The return value is a pointer to a record whose size is 
arrayjecoroBytes. 

Last returns a pointer to the element at the end of the array. 
This is equivalent to anay.At(array.size)L 

ManyAt (L ho^iany: LONQDsrr> TArray; 

1 Is an ordinal position in the array. 
howMany is a number of elements. 

ManyAt returns an array of size howMany containing copies of 
the elements from the original array beginning at position 1 and 
continuing throuo^ ho^iany elements. 

MemtelBytes: INTEGER; OVERRIDE; 

MemberBytes returns arrayjecoroBytes, the number of bytes in 
each element of the array, as was specified in the bytesPerRecord 
parameter of the TAiiay.CREA7E call. 

Pos (aften LONGWT; pRecofd: PU> LONGINT; 

after is a the position in the array. 

pRecord is a pointer to a record. 

The return value is a position in the array. 

Pos searches the array, beginning at position after+l. It returns 
the position of the first element found that is equivalent to the 
record pointed to by pRecord. If no such record is found, Pos 
returns after. 
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PlItAt (t LONGINT; pReCOTft Pttfc DEF AULT; 

1 is an ordinal position In the array. 

pRecord is a pointer to a record whose size is bytesPerRecord. 

PutAt deletes the element at position t and replaces It with the 
record pointed to by pRecord. 

This method is used for a simple subscripted fetch. Instead of 
using •* - 

ordArrayBl- x; 

as you would to replace element 1 in the Pascal fiPSWf ordArray, 
you write 

my Array PutAt(L ©xjc 

to replace element i In the TArray myArray. 

scanner. TArrayscamer; 

Tne return value is an arrayScanner for tnis array. 

scanner returns an object of class TArrayscamer, allowing use of 
arrayScanner methods. Tnis is equivalent to 

array.ScamerFrom (l* scanForward); 

ScamerFrom (firstToScart LONQINT; scanDirecUort TScanDirection): 
TArrayscamer; DEFAULT; 

firstT oScan is a position in the array. 
scanDlrection scanForward or scanBackWard. 
The return value is a new arrayScanner. 

ScamerFrom returns an object of class TArrayscamer, with 
arrayScamerPosltton equal to firstToScan minus one, so that the 
first call to arrayScanner.Scan returns the address of the record 
at firstToScan, 

startEdlt (withSlack: INTEGER); 

withSlack is the new value for holeStd. 

StartEdlt changes thje value of hoteStd to withSlack. The next edit 
call creates a hole of size withSlack,, so that subsequent edit calls 
act more quickly. 

StOpEcfit; 

stopEdit removes the hole from the array and sets hoiestd to (zero). 
Any subsequent edit call removes any hole it forms. 
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FAILURE coromQN& Heap cant grow. 

Array > 32K bytes. 



NOTES: 



Deleting from empty array (only checked if the debug 
menu item CHECK LIST INDICES Is onX 
Subscript out of range (only checked if the debug menu 
item CHECK LIST INDICES is onX 



1. An array is a space-optimized list it is similar to a list object, but 
where a list contains object handles, an array contains records. 

2. While an object can have references to it in several lists, a record can be 
in only one array at a time. 

3. Use instances of TString when you need to store a string of characters or 
one-byte values. 

4. list operations are more convenient and often run faster than array 
operations: TAnay has a relatively limited interface. 

5. Arrays have three modes: create mode, eat man and static moos 

6. When you first create an array, it is in create mode. You define an 
initialSlack value in the CREATE call. The array is given enoucp empty 
space to hold initialSlack records. That space Is the hole. As you add 
members, the space in the hole Is used for the new members. The amount 
of space allocated to the array does not change until you fill up the hole 
with array members. You can also call array.StopEdiL which removes the 
hole from the array. 

7. When the hole is filled, the array enters static mode. In static mode, no 
hole is ever maintained, if you add a member, the array is copied into a 
space large enough to hold the additional member. If you delete a 
member, the extra space is freed. 

8. Enter edit mode by calling array.StartEdBt(withSlack). in edit mode, a hole 
big enough for withSlack elements is initially created. As you add 
members, the size of the hole decreases. Tne hole is always positioned 
after the last element inserted or after the position occupied by the last 
element deleted. When the hole is entirely filled, the space allocated to 
the array is increased, so there is a new hole big enough for withSlack 
members. If you delete members, the extra space is added to the hole. 
Call array^tdpEdlt to stop editing. Any space taken up by the hole is 
then freed. 

9. array^ize « arrayjecordBytes cannot exceed 32767. 

10. You can access array elements faster by creating an alias for the array, 
and then using double-indirect pointers. The array must have no hole, or 
a hole at the end of the array, for this method to work. 
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Assume you have created an array similar to this one, where 
TYPE T- RECORD 

fftewsj 

END; 
V^* my Array: TArrayfOF Tfc 

Also, assume you have created your array in some way such as this: 

myAnrayr- TArrayjCREATE (^bl+ he&p, InitalSize, SEEOFtTfc 

To access the array more quickly than you could with At and PutAC 
declare some variables like these: 

TFastT- RECORD 

headen TArrayHeader; (A pre-defined ToolKlt typej 

records: fiFtRAY[L.6aoQ OF T; (me number In Italics is given 

here as a n example, it should 
be 32000/SEZEUKI} 
END; 
TPFsstT- "TFastT; 
THFastT- "TPFastT; 

Then you can access the array like this: 

ThFastTtaT'jBcordsUt- tRec; 
tRecr- ThFastT(a)"*JBcards[lt 

where tRec is a record of type T. The array bounds in TFastT should be 
chosen to be large enough to avoid range-check errors at run time, but 
must be less that about 32000 D1V SEEOFO). 
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CLASS: TAnayScamer 
SUPERCLASS: TScamer 



DEFINED SUBCLASSES: none 



INHERITED DATA FIELDS: 



R collection: TCollectlon; 
R position: LONGONT; 



increment: INTEGER; 



SCartDone: BOOLEAN; 



R atEntt BOOLEAN; 



DATA FIELDS* 



none 



METHODS 



Tne array being seamed. 
The current position of 
tne scanner. The scanner 
position is always 
between, before, or after 
members: o-before first, 
size*l-after last 
The change In position 
for every scan: 1 If 
scanning forward, -i if 
scanning backward. 
When this is TRUE, the 
next Scan call returns 
FALSE, signalling the end 
of the scan. The VfiR 
parameter of the Scan 
method, which normally 
contains the next record 
in the array, is 
unchanged after that 
Scan call. 

TRUE If the end of the 
array is imminent, so 
that the next Scan call 
will return FALSE. 



CREATE (object: TObjBCfc ltsArray. TArray; itslnltiaiPosition: LONGONT; 
ltsscaroirectlort TScanDlrectlon* TAnayScamer; 

ltsArray is an anray object 

itsmitiaiPQsiUon is the initial ordinal position in itsAnay. 

ltsscanLJirBCUon is scanr orwaro or scanBacicwara. 

TAnayScarmer.CREATE creates an object of type TAnayScamer, 
which is used to access ltsArray. You never call this method 
directly; instead, you use array-Scanner or anay-ScameiFrtm 
Those methods call TAnayScameLCREATE. 
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/>«»« (pRecord: Pti); DEFAULT; 

pRecord Is a pointer to a new member of the array. 

impend adds a copy of the record pointed to by pRecord to the 
array immediately after the current position position is adjusted 
by adding l, regardless of the current increme n t 

Mete; DEFAULT; 

Delete deletes the record at the current position, position is 
adjusted by adding arrayScannerJncrement 

DeteteRest; DEFAULT; 

Delete deletes all records after the current position, if 
arrayScannerJncrement is +1, or before the current position, if 
arrayScannerJn cr ement is -L position is unchanged Any 
subsequence anayScanner^can call returns F^-SE. 

Done; 

Done signals that you are finished using this arrayScamer. The 
next call to arrayScamer.Soan returns FALSE, as if the end of the 
array had been reached Unlike when the end of the airay is 
reached, however, the returned record in Scan remains unchanged. 

Free; OVERRIDE; 

Free deallocates this arrayScamer object 

Obtain: PtT; DEFAULT; 

The return value is a pointer to a record in the array. 

Obtain returns a pointer to the current record. For example, 
where s is an arrayScamer created with myArray-Scamer 

«- sXtotain*; 
is the same as 

*- myArray.At; 

Replace (pRecont Pbfc DEFAULT; 

pRecord is a pointer to a record. 

Replace removes the current record from the array and replaces 
It with a copy of the record pointed to py pRecord. The new 
record is now the current record. 
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Scan (V/tf* pNBXtReoont PtI* BOOLEAN; DEFAULT; 

pNextRecord is a pointer to the next record from the array. 
The return value is FfiLSE if the end of the array has been 
reached or arrayScamer-Done has been called. 

Scan begins at the beginning of the array and, each time it is 
called, returns a pointer to the next record. The record pointed 
to by the returned pointer is referred to as the current record. 
The value of Scan is true until scan is called after the last 
record in the anray is reached or until arrayScamerJDone has 
been called, if the end of the array was reached, and Done was 
not called, the value of pNextRecord is ML. If Done was called, 
pNextRecord keeps the last value it had. When scan returns 
FALSE, the scanner is freed. 

Seek (anayPos: LONG1NT); 

arrajPos is the location to which you wish the scanner to move. 
arrayPos - is the beginning of the array. 

Seek moves the current scan position to arrayPos. It transfers no 
data. 

Skip (deltaPos: LONQ1NT1; 

deltaPos is the number of elements you wish the scan position to 
move within the array. A positive value moves the position 
toward the end of the array; a negative value moves the position 
toward the beginning of the array. 

Skip moves the scan position deltaPos bytes forward or backward 
within the anay. arrayScamerJncrement is ignored. Skip 
transfers no data. 



NOTES: 



L An arrayScarmer is used to access a stored data array, to scan it, and to 
manipulate its individual elements. Use TArrayScamer and its subclasses 
to scan arrays. 

2. You may have more than one arrayScarmer for the same array at the same 
time. However,, if you do, you cannot use Append, Delete, or DeleteRest 
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CLASS: TBand 

SUPERCLASS: TArea 

DEFINED SUBCLASSES: none 

INHERITED DATA FIELDS: None that are significant See TArea for Information. 

DATA FIELDS: window: TWlndow; The window containing this 

vbond 

panes: TList fof TPane}; The panes contained In this 

bend 

panel: TPaneb The panel containing this band. 

scroller: TScroller; The scroller for this band. 

scrollDlr. VHSelect; The orientation of this band v If this Is a 

row of penes with a vertical 
scroll bar; h If this is a column 
of panes with a horizontal scroll 
bar. 

METHOD YOUR APPLICATION MIGHT CAUL: 

ChUdWlthPt (pt: Point; cWldList: TList; VAR nearestPt: Point}: TArea; 

pt is a point In window-relative coonflnates. 
childLlst is a list of areas contained within this band 
nearestPt is the point in the returned area closest to pt 
The return value Is one of the areas from childLlst 

CrtldWithPt first finds the point in bandimerRect closest to pt it 
then the compares the new point to the outerRects of all the areas 
in childLlst When it finds the area that contains the point it finds 
the point in that area's imerRect that is closest to the point That 
value is returned as nearestPt The area containing nearestPt is the 
return value, 

ReslzeOutside (newOuteiRect: Rectfc 

newOuteiRect is the bounding box 

ReslzeOutside is used to change the size of bendouterRect It sets 
the new value of bandOuteiRect invalidates as needed, adjusts the 
size of the scoller, and resized all panes in the bend (by calling 
bendResizePanesX It can be re-implemented to do higher-level 
operations on the bend such as resizing areas contained within this 
band 

ScnfllBy (deltaLCdt LONGINT); 

deltaLCd is the amount the bend is scrolled in view coordinates. 

TBandScroUBy scrolls the band by the given amount Bands only 
scroll in one orientation, bendscrollDir. The thumb is also moved / 
positive deltaLCd scrolls towards the end of the view, while a 
negative value scrolls towards the beginning. When deltaLCd is o 
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(zero), the ScroUBy does not scroll, but, Instead, invalidates the entire 
bend. The next time Update is called, the band is redrawn. This 
feature is used for resizing bands, 

ScroUTo (viewLCd: LONGINT); 

viewLCd is the position in the view the band is scrolled to, in view 
coordinates. 

TBancLScrollTo scrolls the band t>$ the given amount viewLCd Is 
placed in the top left corner of the bend. The thumb icon is also 
moved. 

ThumbTo (newThumbPos: INTEGER); 

newTTumbPos is the desired position of the thumb Icon. is the 
position at the beginning of the document, and 1000 is the position at 
the ena 



TBandThumbTo moves the thumb to the given position, and scrolls 
the band by the resulting amount 



NOTES: 



1. TBand is never subclassed or instantiated by application programs, and you 
almost never call it 

2. You can call the methods listed above in order to implement scrolling in 
your own way. 

3. Methods of TBand are not normally used for scrolling. Instead, use 
TPaneLRevealLRect to bring information in the panel into view. 
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class: TBodyPad 

SUPERCLASS: TPad 

DEFINED SUBCLASSES: none 
INHERITED DATA FIELDS: See TPad. 

DATA FIELDS: maiginPadb TMargftPad; The margtaPad that defines the 

^margins surrounding this bodyPad 
nonNUUBody: Rett; The section of the view that 

appears in this bodyPad. 

METHODS: None that are Important for applications. 

NOTES: 

1. This class defines a pad used in creating the printaDle picture of a section 
of a view. 

2. A bodyPad contains a printable picture of a section of a view. Each page 
of the entire printable image is made up of the bodyPad and a marginPad. 




marginPad 



bodyPad 
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CLASS: TCllpdoard 

SUPERCLASS: TDocManager 

DEFINED SUBCLASSES: none 

DvKRTTED DATA FIELDS: None are important 

information. 

DATA FIELDS: R hasVtew: BOOLE^sf 

R hasPicture: BOOLE/** 

R nasunlvereaiText: boolew; 



METHODS: 



haslcort BOOLEAN; 
R cuttingToob LONGINT; 

R GUttingpIDOesslD: LONGINT; 
clipOopy: TFfteScarrar; 

None you need. 



See T D ocManager for more 

FALSE indicates there is no 

TooiKlt representation of the data 

in the clipboard. 

FALSE indicates there is no 

universal graphics picture of the 

data in the clipboard. 

FALSE indicates there is no 

universal text version of the data 

in the clipboard. Note that you 

need to use the universal Text 

Building Block to use universal 

text 

TRUE if there is an icon reference 

available. 

Contains the tool number of the 

application that last loaded the 

Contains the OS process ID of the 
process that last loaded the 

A learner on a file containing a 
copy of the clipboard before 
conversion. 



NOTES: 



L The clipboard object acts as a directory to the clipboard which stores the 
last data cut cur copied from any document on the desktop. 

2. Every process has its own clipboard. 

3. You may want to inspect the clipboard's data fields to find out whether or 
not you can copy information from the clipboard. 
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CLASS: TDottection 

SUPERCLASS TObjBCt 

DEFINED SUBCLASSES: TArray 

TFUe 
TUst 
TStrlng 

BMHERTTED DATA FIELDS: none 

DATA FIELDS R size: LONGINT; 



RW dynStart: INTEGER; 



hOleStart: INTEGER; 



holeSIze: INTEGER; 



hOleSttk INTEGER; 



The number of real elements in this 
collection, not counting the hole. 
This is a LONGINT for the benefit 
of huge collections, such as remote 
data bases. It is always in the 
NTEGER range for instances of 
TUst TAnay, and TStrlng. 
The number of bytes from the class 
pointer to the dynamic data area 

means hole at the beginnlng^aiue 
of size means hole at the end. 

The initial size of the hole, 
measured in number of collection 
members. 

How much to grow the collection 
by if the holeSIze goes to 0. 



METHODS: 



create (object- TObjBot; heap THaep; Wttasiac*: NTEGER* 
TDoUecUorv 

object in this case, must be an object that was allocated by the 
subclass** CREATE method by calling NewOynObJect 
InitiaiSlack is the size of the Initial hole* in members. 

TDouecuoaCREATE creates an object of type TCouection. 
InltiaiSiaDk is a hole for ooueotton members, if WtialStock is 
greater than 0* the insert methods can be used to initialize the 
collection without allocating any storage. This is never called 
directly; it is called by CREATE methods of subclasses. 

Clone (heap: THeep> TObJect; OVERRIDE; 

heap is an available heap. 

The return value is a new collection that has the same contents and 

characteristics as the calling coUectioa 

TCollectionxaone creates a copy of the coUectioa 

MemberBytes: INTEGER; /«STRACT; 
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The return value is a size, In bytes. 

TCoUectloaMemberBytes does nothing. In subclasses, MembeiBytes 
returns the number of bytes used to store a collection member. 

Equals (otherColtecttort TOoUectior* BOGLES; 

otherCoUection is another collection. 

The return value tells whether or not the two collections are equal. 

TCollecUooEquals tests whether this collection contains the same 
elements as otherCollectloa 

StartEdlt (withSteDk: INTEGER); 

wlthSlack is the new value for hoiestd. 

TCoilectioaStartEdlt changes the value of hoiestd to wltnsiack. 
The next edit call creates a hole of size vithSlack, so that 
subsequent edit calls act more quickly. Holes that form from edit 
calls are not closed until the next call to ooilectioastopEdiL 

StopEdit; 

TCollectiooStopEdit removes the hole from the collection and sets 
hoiestd to (zero). Any subsequent edit call that has no hole 
removes any hole it forms, until the next call to startEdlt 

insManyAt (k LONQINT; otherCoUection: TCollectioo; index, howMany: 
LONGINfT); 

i is an index number for an element of the coUectioa 

otherCoUection is a collection that contains the elements to be 

inserted. 

index is an index number for an element of the otl mi Collection. 

howMany is the number of elements to be inserted. 

TDottectkmJnaManyAt inserts elements from a collection into this 
collectloTV 

tasNullsAt ft, howMany. LONGlNTfc 

i is an index number for an element of the coUectioa 
howMany is the number of null elements to be inserted 

TCttUecttorUnsNUUsAt inserts null elements into the collection after 
the given point 

PRIVATE ^ETHCOS (Only called by subclasses): 
Cheoklndex (index: LONGUNT); 

Index is an index number for an element of the collection. 

TOoiiecttoiiChecwndex tests to be sure that Index is greater than i 
and less than or equal to collectloasize, if the dubug menu CHECK 
list indices command was chosen. 
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AddrMamber (k L0NG1NT> LONGaNT; 

i is an Index number for an element of the collectloa 

The return value is the address of a member of the collection 

TDoUectloaAddiMember returns a value that can be interpreted as a 
pointer to a given element of the collectloa The address is valid 
only momentarily, as collections (like all objects) are stored 
dynamically, and can move at an> time. 

OopyMembers (ostAddr, startw^ 

dstAddr is an address. 

startlndex is the index number for the first element of this collection 

to be copied. 

howMany is the number of elements to be copied. 

TGoUectloaGopyMBmbers copies elements from the collection to 
dstAddr. 

EdttAt (attadex: LONGUNT; deltaMembers: INTEGER); 

atlndex is the index number for the place in the collection where the 

edit is to occur. 

deltaMembers is the number of members to insert or delete. 

TOoltecUoaEditAt adds or deletes members of the collectloa If 
deltaMembers is greater than 0, the members are added, if 
deltaMembers is less than 0, members are deleted. This method does 
all the work (resizing the collectloa moving members around, 
relocating the hole) except actually copying members into the 
collectloa It is called by other edit methods. 

ResizeCoU (membersPlusHole: tTTEQERk 

membenPiusHote is the capacity of the collection after this method 
is called. Its value is equal to ooUeottoasize plus the hole. 

TOoUecttoaRestzeOoil changes the amount of space allocated to this 
collection to n ^tgnPlusHoie«mBmbeiBytes. 

sniftcoil (afteisroMBX, arterOsttttex, howMany: B^QERfc 

afterSrcttfex is a position in the collectloa 
afteiDstlndex is a position in the collectloa 
howMany is a number of elements. 

TCoUecUoaShlftCoU moves the hole b y movi ng howMany elements 
rioJU afterSrdndex to be right afterOstlndex 

NOTES: 

l. TColiectlon defines the basic structure for ail groups of objects used in 
the ToolKit This includes files, arrays, lists, and strings. 
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2. TCollectlon is an abstract class; no objects of type TCoUectlon are ever 
created, instead, you create objects of the subclasses of TCollectlon: 
TAnay, TUst TFlie, ana TStrtng. 

3. collectloasize Is the number of actual members, not counting the hole. 

4. You can Ignore the hole when using most methods. However, If you use 
the private methods, you must take the hole Into account 

5. Since collections may be given more space* than Is needed to hold the data 
In them, there may be an unused "hole" somewhere In the storage block. 
The fields holeStart and holeSlze specify On member-sized units) the 
starting index of the hole and the length of the hole. When holeSlze is 
zero, there Is no hole. If members are added when there Is no hole, the 
storage block is expanded to allow for at least another holeStd members. 

6. collections have three modes: create mod% eat mod* and static mode 

7. When you first create an collection, it is in create mode. You define an 
inltialSlack value in the CREATE call, "me collection is given enough 
empty space to hold lnltialSlack elements. That space is the hole. As 
you add members, the space in the hole is used for the new members. 
The amount of space allocated to the collection does not change until you 
fill up the hole with collection members. You can also call 
GdUectioostopEdlt, which removes the hole from the collection. 

8. When the hole is filled, the collection enters static mode. In static mode, 
no hole is ever maintained. If you add a member, the collection is copied 
into a space large enough to hold the additional member. If you delete a 
member, the extra space is freed. 

9. Enter edit mode by calling oollectioaStartEdltMthSlack). In edit mode, a 
hole big enough for wlthSteck elements is Initially created. As you add 
members, the size of the hole decreases. When the hole is entirely filled, 
the space allocated to the collection is Increased so there Is a new hole 
big enough for wttftSiack members. If you delete members, the extra 
space is added to the hole. Call ooUecdoaStopEdlt to stop editing. Any 
space taken up by the hole is then freed, "me hole is always positioned 
after the last member inserted or after the position that was occupied by 
the last member deleted 
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CLASS: TCommand 

SUPERCLASS 
DEFUSED SUBCLASSES: 

BM-CRTTED DAT A FIELDS: 



TObjBCt 

TCutDopyOommend 
TPasieCommand 

none 



DATA FIELDS: R cnvflsfcitiber: TCmdNumber; 



R Image: Tlmage; 



R undoeble: BOOLE/** 
R doing: BOOLE/V* 



revelation: TRevelation; 



w 



vThe command number of the menu 
Item that describes the command. 
The Image (usually a view) to which 
the command applies, or no. If the 
data is stored in the window. 
TRUE means that this command 
can be undone. 

This value is TRUE if the last call 
to Perform was in doPhase or 
redoPhase. 

Determines how much of the 
selection should be automatically 
scrolled into a pane when the 
command is performed. Can be 
none (no scrolling), some (scroll to 
show some part of the selection), or 
all (scroll to display the entire 
selection, if possible} 

unhfliiteeefdre: /VKAY pCmdPhase] OF BOOLEAN 

TRUE tells the ToolKlt to remove 
the highlighting from all selections 
before Perfdrm(cmdPhase) is called. 
The defaults are TRUE. 

MiiteAnen /«ray DOmdPnase] of boole/v* 

TRUE tells the ToolKlt to add 
highlighting to all selections after 
Perf0rm(cmdPhase) is called The 
defaults are true. 

METHODS YOUR /WUCATION MUST OVERRIDE: 

CREATE (object: TObJect; ltHeep: THeeps; ltsOrnNumber. TCmdNumber; 
ltslmage: Tlmage; lsUhdoebte: BOOLE/** ItsRevelattort TRevelation* 
TCommand; 

ltsomdNumoBr Is the command number of a menu command, 
ltslmage Is the image to which the c ommand applies, usually a view, 
or NIL if the data is stored in the window. 
isUndoable Indicates whether or not the c o m mand can be reversed. 
itsReveiatlon determines how much of the selection is scrolled into 
view when Perform is called. The value can be revealNone (no 
scrolling), revealSome (scroll to show some part of the selection), or 
revealAU (scroll to display the entire selection, if possible), if the 



w 
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selection 1$ already fully displayed, this field has no effect See 
TPaneLRevealLRect for more Information. 

TCommandCREATE creates an object of type TCommand. 

Perform (prophase: TCmtPhase); DEFAULT; 

cmdPhase Is either doPhase, undoPhase, or redoPhase. The first time 
Perform is called, the cmdPhase if doPhase. After that, undoPhase 
and redoPhase alternate. 

Perform Is called when the c omm a n d is done, undone, or redone. If 
the comman d Is implemented using a filter, Perform often Just 
invalidates (see TPaneUnvalRect) the changed areas of the view. If 
the c ommand is not Implemented with a filter. Perform should carry 
out the action of the command . 

METHOD YOUR APPLICATION WILL CHJL: 

CREATE (object: TObJect; ltHaapc THeap; ItsCmdNumben TCmdNumber; 
itslmage: Tlmage; lsUhdoable: BOOLErtsfc ltsRevelatiort TRevelatlon): 
TC omman d; 

See above. 

METHODS YOUR WPUCAT10N MIGHT OVERRIDE: 
Commit; DEFAULT; 

Commit is called when a command has been done and can not any 
longer be undone. (Commit is usually called when another command 
Is given by the user.) See note 4. TOommamcommlt does nothing. 

EachVlrtualPart (PROCEDURE DoToObJect (ob> TOb JectJc 

PROCEDURE DoToObJect is a procedure that takes an 
object-reference of type TObJect as an argument DoToObJect 
cannot be a method. It is usually defined as a local procedure within 
some method. 

EacnvirtuaiPart Is used In Implementing a filter. A virtual part\% a 
selectable part of the set of objects. Every virtual part must be an 
object DoToObJect 1$ a procedure that acts on the virtual part 
When taking some action that depends on the action of undoable 
commands, call Image or view-EacrtvlrtualPart giving as the argument 
the method you want to apply to the objects. If the last comman d 
has been done (that Is, If comrnancLPerform was last called with 
doPhase or redoPhase)^ comman O EachvlrtualPart Is called. 
commanaEachVlrtualPart calls FllterAndDo, which alters the object 
before calling DoToObJect 

You do not have to reimplement TDomrrand£ac*MrtualPart except 
for comma n d s that act on more than one virtual object at a time. 
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For example, if the command involves reordering the objects in your 
data set, implement commencLEachVlrtualPart so that it does the 
reordering. 

When you do not reimplement TOommand£achVirtuaiPaflrt implement 
commandFilter/^idDo for commands that act on one virtual object at 
a time. 

lOaofnandjEachVlrtuQiPart calls view or imagejEachActualPart to get 
the actual set of data. (You have to implement EachActualPart See 
the reference sheet for TVIew or TImage.) EachActualPart must 
return a list of objects that together make up the data set 
TCornmanOEachVirtualPart calls Filter/VxOo once for each object in 
the list 

Do not call (MmmanOEacnvirtualPart directly. However, when you 
are implementing your own version of axTirandfacnvirtualPart, you 
may call TQjnrranttEachVirtualPart from your method. 

FilterAndDo (actuaiOb> TObjBDt; PROCEDURE 
DoTcObJectffflteredObtTObJectfc 

actualObJ is an actual part of the document 

DoToObJect is a procedure that takes an object-reference of type 
TObject as an argument DoToObject cannot be a methoa 

FllterftidDo is used with filtered command s . It is Intended to check 
actualObJ, and see if the c omman d would have changed it If so, 
FilterAndDo should change the object according to the action of the 
command, call DoToObject giving the filteredObj as an argument, and 
then change the object back to its unaltered state. 
TCommandLFilter/VidDo calls DoToObject but does not filter the 
object first 

Free; 

Free is called by the ToolKit when a comman d can no longer be done 
or undone. TComman d Free deallocates the command object 
Subclasses should override TDomman&Fiee if there is anything other 
than the command object which should be deallocated at the same 
time. 



NOTES: 



1. All commands that make significant changes to the document should 
return an instance of TCommand or a des c enda n t of TCommand to the 
ToolKit See the Lisa User Interface Standards fax standards. 

2. The ToolKit tells the c ommen d object to Perform with cmdPhase equal to 
doPhase. If the user chooses undo from the Edit menu, and the oomri iy id 
object can be undone, the ToolKit tells the comman d object to Perform 
with cmdPhase equal to undoPnasa If the user again requests undo, the 
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ToolKlt tens the commend object to Pexftem with cmCPhase equal to 
redoPhasa Subsequent undo requests alternate between undoPhase and 
reaoPhasa 

3. When another command is sent to the ToolKlt the ToolKlt first tells the 
last command object to Commit (unless the com m a nd has been undone) and 
then to Free. If the last Perform was with undoPhase, the commit call is 
omitted. 

4* The Commit method is intended for use with command s that can not be 
easily reversed, but that you want the user to be able to undo. You 
implement such a command so that the action of the command is not 
actually carried out the when the command is given. Instead, you make 
the display appear as if the command was carried out This is referred to 
as filtering 'the display. If the command is then undone, you can simply 
display the true state of the data If another com ma nd is given, call 
Commit to actually change the data 

5. If the command is Implemented using a filter, the action of the c ommand 
Is not carried out by Perform. Perform usually simply invalidates regions 
of the view that would be changed by the comman d . 

6. All methods that would be affected by the action of filtered c ommands 
are implemented so that they call TView£achVirtualPart Give a 
procedure that acts on a TObJect-type reference as an argument to 
TViewJEachVirtualPart If the command has been done (that is, 
commandPerfoim was last called with cmcPhase - doPhase or redoPhase), 
windowPilterDispotch is called. windowiTlterCttspetch calls 
commandEachVirtudPart If the command alters the set of objects 
displayed in the view, you should reimplement command L EachVlitualPart so 
that it produces the correct set of virtual parts. 
TCommand£acr>VlrtuaiPart simply passes each object from 
view-EachActuaPart to ocmmandLFllterAndDa If the command alters the 
individual parts of the view, you should implement oommandJFliterAndDo 
so that it checks whether or not the command should have changed that 
particular object ana if it should have, changes the object so that it 
appears correctly. The procedure given to EachVirtualPart is then called, 
with the altered object as its argument When that procedure completes, 
the object is changed back to its original state, and FlltertadDo is given 
the next object 

7. Note that you or a building block must implement Perform, and often also 
implement Commit for all your application's commands, except for 
outCopyComrnand and pasteCommand, whose Commit and Perform methods 
are implemented in the ToolKlt For aitCopyCommand, you (or a building 
block) implement DoCutCopy and for pasteOommand you (or a building 
block) implement DoPacta 

a Some commands do not appear in a menu in the menu bar. An example of 
this would be where, in a graphics program, the user selects a box and 
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then drags it across the window. In that case, the user is essentially 
giving a move command. According to the user interface Standards* 
because such a command makes a significant change to the document it 
must be Implemented using a comman d object In addition, there must be 
a name for the command, so that the Edit menu can tell the user what 
command can be undone. See note 9 below. 

9. To implement a comm a nd that does not appear in the menu bar, put the 
command name in your phrase file with a'menu number greater than ioa 
This is referred to as a uizzyord^tsxtL You put the name in the phrase 
file so that you can use it later to display the name of the command in 
the Undo menu item. When the action that is referred to by the buzzword 
menu occurs, create a command object for the command from within your 
application. Call windCNrPerfonTCommarx<command) where command was 
created by selecUooNewCommand or window JstewCtommand. 

10. If a command makes a significant change to the document, but you do not 
want to, or cannot, implement undo, create an instance of TCommand 
(rather than an instance of a descendant of TOommancO with the wDoatoe 
field set to F^SE and Implement the command entirely within 
NewOommanct after first calling window.CommitLast 

11. If commands are not yet clear to you, do not dispair. To fully understand 
commands and command flow, you will probably need to study some 
sample applications. Please refer to the ToolKit Segments on com ma nds. 
After you have studied that, examine the sample programs carefully. 
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CLASS: TOutGopyOommand 
superclass: TOommand 

DEFINED SUBCLASSES none 

INHERITED DATA FIELDS: R cmdNUTten TCmdNumteT; 



R view: TVIew; 



R undoawe: BOOLEAN; 



R daln$ BOOLE/** 



revelation: TRevelatlon; 



The command number of 
the menu Item that 
describes the command. 
The view to which the 
command applies, or NIL 
if the data is stored in 
the window. 
TRUE means that this 
command can be 
reversed. 

This value is TRUE if the 
last call to Perform was 
in doPhase or xedoPhsse. 

Determines how much of 
the selection should be 
automatically scrolled 
into a pane when the 
command is performed. 
Can be none (no 
scrolling), some (scroll to 
show some part of the 
selection], or all (scroll 
to display the entire 
selection, if possible). 

w unHiilteeefare: /«ray rrcmdPhase] of boolean; 

true tens the TOOlKit 
to remove the 
highlighting from all 
selections before Perform 
is called. 

W WliteArten /¥*RAY [TCrndPhase] OF BOOLEAN; 

TRUE tells the ToolKit 
to add highlighting to all 
selections after Perform 
is called. 



DATA FIELDS: R isQlt BOOLE/** 



Tells whether the data is to be cut (TRUE) or 
Just copied to the clipboard (F^-SE). 
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METHODS YOUR /WUCATION MUST 0*€RWDE: 

CREATE (object: TObJect; ItHeap: THeap; ItsCmdNumber. TCmdNumber; 
ltslrnage: TTmage; isCutCmcfc BOOLEAN): TCutOopyCommancfc 

ItsCmdNumber is the command number of a menu command. 
ltslrnage the image to which the command applies (usually a view), or 
NIL if the data is stored in the window. 
isCutCmd indicates whether this is a cut (TRUE) or copy (F7U.SE). 

TCutCopyOonrvnand.CREATE creates an object of type 
TtXitCopyOommandL 

DoCutCopy (cUpSelectlort TSelectlon; deleteOriglnal: BOOLE/Y^ cmdPhase: 
TCmdPhase); 

cUpSelection, when cmcFhase-doPhase, is a selection in the clipboard 
that you can replace with a copy of the seiectPanel's selection. 
When cmtPhase-undoPhase or redoPhase, clipselection is the 
selection the outoopyoommand inserted in the cllpboara 
deleteOrlginal Indicates whether the objects are to be cut from the 
document (TRUE) or Just copied to the clipboard (Fft.SE)i it is 

equivalent to the value of SELFJsCut _^ 

cmdPhase is either doPhase, undoPhase,, or redoPhasa 

Docutoopy executes the cut or copy. The first time Docutoopy is 
used, the cmdPhase is doPhasa After that, undoPhase and redoPhase 
alternate. This routine is called by Perform after Perfbim sets up 
the clipboard data segment You must implement Docutoo p y so that 
it does the following: 

• When cmdPhase is doPhase, clone selected objects and put them in 
the clipboard and If deleteOriglnal Is true, delete the selected 
objects from the document 

• When cmdPhase is undoPhase, and deleteOriglnal is TRUE, restore 
the selected objects to the document You do not have the change 
the clipboard; the ToolKit does that for you. 

• When cmdPhase is redoPhase, and deleteOrtglnal is TRUE, delete 
the original objects from the document You do not have the change 
the clipboard; the ToolKit does that for you 

When deleteOriglnal is FrtJSE (that is, this is a copy command), 
nothing Is done by DoCutCopy on undoPhase or redoPhasa 
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METHOD YOUR APPLICATION MK3HT OVERRIDE: 
Commit; 

You can override Commit if you want to implement cut so that it 
uses a filter when Perform is called. In that case, cutOopyjCommlt 
removes the information from the document If you override this 
method you should call TCutcxpyCommanacommit at the beginning 
of your method. 

METHOD YOUR WUCATION WILL CALL: 

CREATE (object- TObJect; ItHeap: THeap; ltsCmdNumben TOndNumber; 
itsVlew: TView; isCutCmd: BOOLE/V* TCutOopyCXmmand; 

See above. 

INTERNAL METHOD: 

Perform (cmdPhase: TOmdPhasefc 

cmdPhase is either doPttase, undoPftase, or redoPhase. 

TCutOopyOommandLPerfoim calls outCopyOonirandyDoCutOQpy to 
execute the cutcopycommand. The first time Perform is used, the 
cmdPhase is doPhase. After that, undoPhase and redoPhase alternate. 
You will have to override Perform if you want it to put a filter over 
the data rather than performing the cut immediately. In that case, 
use Commit to call DoCutCopy. 

NOTES: 

1. See TCommand for general information on command implementation. 

2. TCutCopyCommand is used to cut the selected objects from the display 
and copy them into the clipboard. The objects are always copied into the 
clipboard, no matter whether the operation was a cut or a copy. 

3. Building blocks often override and implement Its action, otherwise, you 
must override this class to create cut/copy command objects. At a 
minimum, you must implement DoCutCopy in every subclass you define. 

4. See the ToolKlt segments and sample programs for examples of use of the 
c u tcopycommand. 
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CLASS TDialp03OX 

SUPERCLASS TWindOW 

DEFINED SUBCLASSES! none 

INHERITED DATA FIELDS: R panels: lUst (OF TPanelfc The panels in the cflaiogBox 

There is always at least 



panelTree: TAiea; 



one. See class TPaneL 
When the window contains 
no panels (which happens 
momentarily during 
BlankStationary) contains 
NIL. When the window 
contains one panel, 
contains the panel. When 
the window contains more 
than one panel, contains a 
TBranchArea that is the 
root of a tree of panels. 
Always MU since this is a 
dialog box window. 
The panel with the active 
selection 

The selectPanei during the 
last command. 
The panel where the mouse 
button was last clicked. 
The clickPanel during the 
last comman d . 
The window with the 
active selection Either 
SELF or its window. 
undoSelWindow: TWindow; The window with the 

active selection during the 

last command. 

ORD of the pointer to the 

Window Manager's 

grafPort 

Tells whether or not there 

is a Resize Box. 

If TRUE, the Toolkit 

should believe the window 

manager's idea of the size 

of the dialog box; this is 

F^SE (for example) when 



dialocpox: TDldUxjBox; 
R selectPanei: TPanel; 

undoSeiPanet TPanel; 
R clickPanel: TPanel; 

undoClickPaneL* TPanel; 
R selectwindow: TWindow; 



wmgriDe TWindowD 

R isResi2able: BOOLEAN; 
believewmgn BOOLEAN; 
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the application creates the 

dlalogBox object before the 

dialog box is put on the 

screen. 
maxlnnerSize: Point; The (flalo^ox size the 

user explicitly set by using 

the grow Icon. 
changes: LONGINT; Not significant for 

dkflogBoxes. 

Not significant for 

(flahxftoxes. 
prlnterMetrlcs: TPrinterMetrics; 

Not significant for 



R lastCmd: TCommend; 



pgSzOK: BOOLErt* 

Pf^gOK: BOOLEAN; 
penelToPrlnt: TPanel; 
obJectToFree: TObJect; 
R imerRect: Rect; 



R outeiRect: Red; 



dlalocjBoxes. 

Not significant for 

dialocjBoxes. 

Not significant for 

dlatogPoxes. 

Not significant for 

Not significant for 

dialo^oxes. 

Contains the size of the 

dialog box, excluding the 

entire frame. 

Contains the size of the 

dialog box, including the 

frame. 



R parentBranch: TBranchArea; 



DATA FFins keyResponse: TUiResponse; 



menuResponse: TDiResponse; 



Not significant for 
cflakxjBoxes. 

What to do with this dlalotpox 
when the user types a key while 
the box is displayed. From the set 
cflAooepL diDismissDialogpox, 
tflQiveToMalnVslndow, diRefUse. 
What to do with this dialogpox 
when the user presses the mouse 
button in the menu bar while the 
box is displayed From the set 
cfiAccepty diPismlTBtP t iili frf^^ r 
(IGiveToMaln Window, cliRefUsa 
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.dowrtinMalnWlrttaritesponse: TDlResponse; 

wnat to do with this cflaio^ox 
when the user presses the mouse 
button In main window while the 
box Is displayed. From the set 
cttAccept, diDlsmissDialo^Box, 
dIGLueToMalnwindQw, cfiReftjse. 

fteeOnDismissal: BOOLEAN; If TOue, the cflalo^ox object Is 

automatically freed by the ToolKit 
when the fliatotpax is taken down. 

METHODS: 

CREATE (object TObJect; heap: THeep; itsReslzabUlty. BOOLEAN; 
itsHei^it: INTEGER; ItsKeyResponse, ItsMenuResponse, 
ItsDowrtinMalnWIndotftesporee: TDiResponse> TEttalogpox; 

itsReslzabillty indicates whether or not there is a size control box. 
itsHeicjn is the vertical size of the dialog box 
itsKeyftesponse is the dialog's response to keystrokes, from the setr 
diAccept diDismissDialocpox, diGiveTaMainWindow, and cflRefuse 
itsMemResponse is the dialog's response to the user pressing the 
mouse button in the menu bar, from the set* cttAccept, 
diDismissDialot^ox, diGiveTaMainWindow, and diReftjse. 
ltsOownlnMainwlndowResponse is the dialog's response to the user 
pressing the mouse button in the main window, from the set: 
cttAccepi dlPlsmlssPlatogftox, cliGiveToMalnWindow, and diReftjse. 

TUlalogBox£REATE creates an object of type TDlaiogpox. 
/Hvear; 

TDialogeoxj°£pear displays the dialog box. 

BeOismissed; 

TDjalojpoxBeOismfased removes the dialog box from the display in 
the default manner, usually by the user pishing the default button. 

TDlalogpoxDisappear removes the dialog box from the display. 



NOTES: 



L Although this class must be subclassed to be used, that is usually taken 
care of by the Dialog Building Block, which defines class 
TDiatogWlndow. 

2. Dialog boxes are used to gather co m m a n d parameters and settings from 
the user. 
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3. Your application should never call methods of TDialocpox directly. 
Call TWindowPutUpDialo^ox and TWIndow.TakeOownDidlo^QX when 
you need to control a dialog box 

4. To arrange for a cflalo^ox to be freed automatically when it is taken 
down, set the field freeOnDismissal to TRUE after creating the 
dJalotfiox object 
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CLASS: TDocOlrectory 

SUPERCLASS* TODjBCt 

DEFB^CD SUBCLASSES: none 

INHERITED DATA FIELDS: none 

DATA FIELDS window: TWlndow; The window object of this 

document 
classWonck TCiassWortd; Contains information on all classes 

used by this process. 

METHOD YOUR APPLICATION MUST OVERRIDE: 

CREATE (object TObJect; ItsHeap: THeap; ItsWindow: TWlndow; 
ItsClassWortcfc TClassWorldfc TDocOlrectory; 

ItsHeap is the document's heap. 

ltwlndow is the window object of this document 

itsClass World contains Information on all classes used by this 

process. 

7DocDirectoiy.CREATE creates an object of type TDocOlrectory. 

NOTES: 

1. TDocOlrectory is only used by the ToolKlt It is documented here for 
your information. 

2. TDocOlrectory is used to create an object that lists all the classes used 
by a process / and also points to the document's window object 
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••"■CLASS: TDocManager 
SUPERCLASS: TObJect 

DEFINED SUBCLASS: TClipboard 

INHERITED DATA FIELDS: none 

DATA FIELDS: files: 

RECORD 



R volumePrefbc TFllePath; 



R volume: TFllePath; 
R password: TPassword; 



saveExlsts: BOOLE/*i* 



W shouldSuspend: BOOLEAN; 



W shoUWToolSawe: BOOLEAN; 



Desktop Manager volume 
and prefix of OS files. 
For example, a possible 
volumePrefix is 
-P/«APORT-pl01T35t 

Desktop Manager volume 

of OS files. 

The password assigned 

by theuser to this 

docManager*s files. 

Whether Save file is 

known to exist and seem 

readable. 

If TRUE (the default), 

the docManager should 

create and read suspend 

files. 

If TRUE (default is 
FALSE) and the tool is 
opened (rather than a 
document being opened), 
it is allowed to create or 
read files. 



END; 



dataSegmenL 

RECORD 

refnurrt ARRAY [UnaxSegments] OF WTEQER; 

File System reference 



R preludePtr. TPPrelude; 



numbers (refnums) of the 
data segments used. 
A pointer to the prelude 
of the data segment, 
where certain 
information is kept, such 
as a handle that enables 
the process to find the 
window object and the 
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formatting for printer 
Information. 
changes: longont; Number of changes since 



END; 



the last suspend or save. 



R docHeap: THeap; The heap, which begins 

after the prelude in the 
bata segment 

R window: TWlndow; The window object for 

this docManager. 
WR pendingNote: INTEGER; If <> 0, NOTE alert that 

should be displayed when 
the document contolled 
by this docManag e r Is 
next activated. 

R openedAsTooL* BOOLEAN; TRUE If the tool was 

opened Instead of a 
separate document 

METHOD YOUR APPLICATION MUST OVERRIDE: 

CREATE (Object: TODject; ltsHeap: THeap; ItsPathPiefbe TFitePath> 
TDocManager; 

ItsPathPreflx is the name of the volume containing the Desktop 
Manager. Supplied by the ToolKit 

TDocManagerjCREATE creates a doc Ma nager object 

NewWIndow (heap: THeap; wMgrtcfc TWlndowId): TWlndow; DEFAULT; 

heap Is the document heap. 

wMgrlD Is the Identifier assigned to your window by the window 

Manager. 

Newwmoow creates a window object for the document you should 
have this method call CREATE for your descendant of TWlndow. 

METHOD YOUR APPLICATION MGHT OVERRIDE: 

DfltHeapSlZB: LONGSNT; DEFAULT; 

The return value is the default heap siza 

DfltHeapSlze returns the default heap size. This value is docDsBytes, 
a constant defined in UABC, currently 512a You might want to 
override this method to increase that value. 



11-38 



Usa TooiKlt Reference Manual Part U Class Reference Sheets 

OTHER METHODS 

complete (allisweu: BOOLEANfc 

alllsWell tells whether or not there is an error. TRUE indicates 
there is no error. 

Complete signals that the document controlled by this docManager is 
finished processing. 

Close (aftersuspertt BOOLEANt 

afterSuspend tells whether or not this docManager was suspended. 
TRUE indicates it was suspended. 

Close closes the docManagefs files. afterSuspend is true If the 

document was set aside by the user. TDocManager.Close calls 
TDocManeger-CloseFlles. 

CloseFiles; 

TDocManager-CloseFUes closes the files controlled by this 
docManager. you can override this method if your application has its 
own files that must be closed. In that case, end your method by 
calling SUPERSELFjCloseFUes. 

Open (VW3 enoR INTEGER; wmgnDe TWindowlD; WV3 
OperedSuspendeOSOOLJEANfc 

emir is an error number. 

wMgrlD is the identifier assigned to your window by the Window 

Manager. 

OpenedSuspended is TRUE if the document was not closed, but only 

suspended (set asideX 

Open opens the files controlled by this docManager. You should 
never override this method. 

OpenBlank tyfi& eraon INTEGER; wmgrflDe TWlndowlDfc 

error is an error number. 

wMgdD is the identifier assigned to your window by the Window 

Manaoer. 

OpenBlank opens new files for a new document You might want to 
override this method if you have non-standard files to open. 
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OpenSaved (VAR enon INTEGER; wmgrEfc TWlndowD); 

error is an error number. 

wMgrlD is the identifier assigned to your window by the Window 

Manager. 

OpenSaved opens the saved files managed by this docManager. You 

might want to override this method if you have non-standard files to 
opea 

OpenSuspended tyfiR enon INTEGER; wmgrlD: TWindowICfc 

enor is an error number. 

wMgiTD is the identifier assigned to your window by the Window 

Manager. 

OpenSuspended opens suspended files managed by this docManager. 

You might want to override this method if you have non-standard 
files to opea 

Revertversion &fi& erron INTEGER; wmgrEfc TWindowlCfc 

error is an error number. 

wMgrlD is the Identifier assigned to your window by the Window 

Manager. 

Revertverslon reverts to the most recently saved versions of the files 
controlled by this docManager. Any changes made since the files 
were last saved are lost You should never override this method. 

Saveverslon (vw* enon INTEGER; volumePrefbc TFilePath; andContinue: 
BOOLE/Y^fc 

error is an error number. 

volumePrefbc is the ToolKit-assigned prefix for this docManager*s 

files. 

andContinue indicates whether or not the files are closed after being 

saved, true leaves the flies open. 

SaveVBTslon saves the files controlled by this docManager . you 

might want to override this method in order to save extra files, if 
you do, save your files in two stages. First, write out your files 
under temporary names. Then call SUPERSELF^aveVfersioa The 
ToolKit writes out its files under temporary names and, when that 
operation returns successfully, renames the temporary files to the 
permanent names, thus destroying the old versions. Once 
SUPERSELFjSaveverslon returns successfully, change the names of 
your temporary files to their permanent names. 
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Suspend tyfiR erran INTEGER); 
error is an error number. 

Suspend suspends the document controlled by this docManager. 

Suspension Is equivalent to setting aside a document You might 
want to override this method to put your extra files in some special 
state. 

Blntfc DEFAULT; 

Bind Inserts the data segments controlled by this docManager into 
memory. 

unbind; DEFAULT; 

unbind removes the data segments controlled by this docManager 
from memory. 

NOTES: 

1. The application must declare a subclass of TDocManager. 

2. The docManager object keeps tracks of files and datasegments used by the 
process. Every ToolKit process must have a docManager for each open 
window or icon. 

3. The docManager handles document suspension, save, and restore commands. 
It saves the document by writing the contents of the heap to a file. When 
the document is later reopened, the saved file is read back into the heap. 
If you want to save your files in another way, you will have to 
reimplement Saveversioa Suspend, OpenSaveci and QpenSuspendL See the 
interface unit UABC for more information on these methods. 

4. Generally, applications do not need to reimplement any routines except for 
CREATE and NewWlndow, and also do not need to deal with any of the 
data fields of TDocManager. 

5. If you create addlUonal files that need to be managed, you might need to 
reimplement OpenBlank, OpenSaved, and OpenSuspended. 

6. By default, when your process is not active, and it receives a note, the 
active process is interrupted and the note is displayed. If you want, you 
can intercept the note, and set p end l ng^tote to TRUE. The note is 
displayed when your process is activated by the user. 

7. You might need to change the default values of shouldSuspend and 
shouldToolSave, if the user can open the tool directly. Sometimes you do 
not need to create a suspend file because you do not need to save any 
state information. In that case, you might want to set shouldSuspend to 
F^-SE When that is done, the effect of setting aside the tool is the 
same as putting the tool away. As there are no documents to suspend, it 
makes more sense to put the tool away. In addition, you mig^t want to 
set shouiorooisave to TRUE. In that case, when the tool Is put away, the 
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data segments it uses are saved with It When the user opens the tool 
again, the data segments are re-loaded, and the tool is in the state in 
which it was left See the following notes for more infomatlon. 

8. Set shouldSuspend and shoultfToolSave to FALSE if you do not want to 
save any state informaion when the user sets aside the tool and turns off 
the Lisa 

9. Set shouldSuspend and shoultfToolSave to TRUE if you want to save state 
information when user saves the tool. Note that in this case, the user will 
not be able to go back to a blank document unless you provide a menu 
command to do so. 
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CLASS: TFlle. 

SUPERCLASS: TOoUectlon 

DEFINED SUBCLASSES: none 

INHERITED DATA FIELDt size: LONQINT; The number of bytes in the disk 

file. 

Other fields are inhertted> but are irrelevant for files. 

DATA FIELDS: path: TFilePath; The pathname of this file 

password: TPassward; The password for this file. 

scann er s: TList (OF Scanner); The flleScamers for this file 

METHODS: 

CREATE (object* TObjBct; heap: THeep; itsPatrt TFllePafth; itsPassword: 
TPassword): TFile; 

itsPath is the file system pathname for this file. 
itsPassword is the password for this file. 

TFlteCREATE creates an object of type TFIla If ItsFUePath is in 
the catalog, the ToolKit finds out the size of the file, and puts that 
value in fll&slze. If the disk file does not exist fltesize is set to a 

Free; OVERRIDE; 

Free closes the file and releases the heap space used for this file. It 
also frees this file's flleScamers. 

Clone (heap: THeap): TObJect; OVERRIDE; (Illegal) 

heap is the document's heap. 
The return value is a file. 

You should never use this method. It is called by the ToolKit 
occasionally. TFile overrides the TObjBct implementation of Clone so 
that Clone checks file system errors. 

MemberBytes: INTEGER; OVERRE£; 

TFileJ^emberBytes always returns l. 
Scanner: TFlleScamer; 

Scanner creates a fOeScamer for this file. 

ScarmerFrom (firstToScart LONG3NT; mardpc TAccesses> TFUeScamer; 

firstToScan is the place in the file where reading or writing 
should begin, measured in bytes, 
manip is fRead or fWrita 

ScamerFrom scans the file from the given point 
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ChangePassword (V/YR erron NTEGER; newPassworcb TPasswonft 

enor is an error number. 

newPassward is the new password for the file. 

ChangePassword attempts to give the file a new password. If the 
operation is successful, fltepessword is changed to the new value 
and error equals (zeroX If the operation is not successful error 
indicates the reason. 

Delete (V^R error: INTEGER); 

error is an error number. 

Delete attempts to delete the file If the operation is successful, 
error equals (zero). If the operation is not successful, error 
indicates the reason. 

Exists (VAR error: INTEGER* BOOLE/** 

error is an error number. 

The return value Indicates whether or not the file exists. 

Exists attempts to find out if the file exists. If the file does 
exist, the return value is TRUE; otherwise the value is FALSE 
If fiteExists cannot find out whether or not the file exists, error 
indicates the reason. 

WhenModtfled (VAR error. INTEGER* LONGINT; 

error is an error number. 

The return value Indicates when the file was last modified. 

WhenModifled attempts to find out when the file was last 
modified. If the operation is successful, error equals (zero), if 
the operation is not successful, error Indicates the reason. 

Rename &fi& error: INTEGER; newFileName: TFUePathk 

error is an error number. 
newFileName Is a pathname. 

Rename attempts to change the name of the file. If the 
operation is successful, error equals (zero)t if the operation is 
not successful, error Indicates the reason. 

VterlfyPassword (VAR erron INTEGER; password: TPasswonQe BOOLEAN; 

error is an error number. 

password is a string of type TPassword. 

The return value indicates whether the password is correct 

VarlfyPassword finds out whether or not password is valid for the 
file. This ignores SELFjassword. 
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NOTES: 

1. This class is used to manipulate the catalog entry for disk files. 

2. In order to read or write the file/ create a fileScamer. See the reference 
sheet on TFUeScanner for more information. 
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CLASS TFUeScarmer 

SUPERCLASS: TStringScamer 

DEFINED SUBCLASSES* none 



INHERITED DATA FIELDS: 



R collection: TCoUection; 
R position: LONGINT; 



R Increment: INTEGER; 



scanDone: BOOLEAN 



R atEndt BOOLEAN; 



R actual: LONGINT; 



DATA FIELDS 



refnum: INTEGER; 
anon INTEGER; 



The file being seamed. 
The current position of 
the scanner. The scanner 

position is always 
between, before, or after 
members: D-before first, 
slze*l-after last 
The change in position 
for every scan: always +1 
for flleScanners. 
When this is TRUE, the 
next Scan call returns 
FALSE, signalling the end 
of the scan. The VAR 
parameter of the Scan 
method, which normally 
contains the next object 
in the Ale, is unchanged 
after the Scan call. 
TRUE if the end of the 
list is imminent, so that 
the next Scan call will 
return FALSE. 

The number of bytes 
transferred in the last 
transfer operation 

The set of allowable accesse s to 

the file, from the set (fRead, 

fWrite, f Append, fPrivate). 

Trie file system r efer ence number 

for this file. 

The first error or warning 

encountered. 
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METHODS: 

CREATE (object: TObJect; ItsFUe: TFlte; manJp: TAccesses> 
TFileScamer; 

ltsFlle Is a file object 

manlp is a set of allowable accesses to the file, from the set 
(fRead, fWrlte, fi°ppend, fPrivate). More than one can be used at 
a time. 

TFlleScannerjCREATE creates an object of type TFileScamer, 
which Is used to access itsFlia itsFile must exist before a 
fileScamer can be created for it; however, you car) use a 
TFllaCreate call in your TFtleScamer.Creete call, which will 
create the necessary file object 

Allocate (slack: LONGaNTJ; OVERRIDE; 

slack is the amount of space added to the OS file, in bytes. 

Allocate adds empty space to the OS file, so that subsequence 

write operations work more quickly. 

typend (character: CHff$ OVERRIDE 

character is a new member of the file. 

TFlle^ppend can only be called when the flleScanner is at the 
end of the file; that is, when fUeScamex.po$ltton Is equal to 
fll asl ze. Append adds character to the end of the file, posi t io n 
is adjusted by adding l, so that the flleScanner remains at the 
end of the file. 

Close; OVERRODE; 

Close closes the OS file scanned by this flleScanner object The 
file object and the flleScanner object are not deallocated; you can 
use the flleScarrarjOpen method to reopen the OS file. 

Compact; OVERRIDE; 

Compact rewrites the file so that it uses the minimum amount of 
space necessary. Any unused disk pages are returned. 

Delete; OVERRIDE; 

TFileJDelete can only be called when the flleScanner is at the end 
of the file; that is, when fileScamer.posltion is equal to filers. 
Delete deletes the last character in the file, position is adjusted 
hi subtracting i. 

DeleteRest; OVERRIDE; 

Delete deletes all characters after the current position, position 
is unchanged. 
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Done; DEFAULT; 

Done signals that you are finished using this flteScanrer. The 
next call to fUeScamer.Scan returns FALSE, as if the end of the 
file had been reached, unlike when the end of the file is 
reached, however, the returned character in Scan remains 
u nchanged. 

Free; OVERRIDE 

Free deallocates this flleScanner object If this is the last 
filescamer for the file, flteFree is called. 

FreeObject; OVERRIDE; 

Free deallocates this flleScanner object and closes the OS file 
accessed by this flleScanner. The disk file is closed. 

Obtains CHAR; OVERRIDE; 

The return value Is a character from the file. 

Obtain returns the current character. 

Open; OVERRIDE; 

Open opens an OS file previously closed by fileScamer.Ctos& The 
file must have been closed by this flleScanner. 

Replace (character: CHAR); OVERRIDE; 

character is a character that replaces the current character. 

Replace removes the current character from the file and replaces 
it with the given character. The new character is now the 
current character. 

Scan (VAR nextChar: CHAR} BOOLE/Y* OVERRIDE; 

nextChar Is the next character from the Ula 

The return value is FA.SE if the end of the file has been reached 

or ftteScerrarJDone has been called. 

Scan begins at the beginning of the file and, each time it is 
callea returns the next character. The returned character is 
referred to as the current character. The value of Scan is TRUE 
until Scan is called after the last character in the file Is reached, 
or until fiteScarmerDone has been called, if the end of the file 
was reached and Done was not called, the value of nextChar is 
ML. If Done was called, nextChar keeps the last value It had. 
When method Done is called or when the scanner reaches the end 
of the file, the scanner is freed at the next call to scamer.Scarv 

Seek (newPositicrt LONGfflsTQ; OVERRIDE; 

newPositlon is the location to which you wish the scanner to 
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move. fllePos - is the beginning of the file. 

Seek moves the current scan position to newPosition It transfers 
no data 

Skip (deltaPos: LONGIKTlt OVERRIDE; 

deltaPos is trie number of bytes you wish the scan position to 
move within the file. A positive value moves the position toward 
the end of the file; a negative value moves the position toward 
the beginning of the file. 

Skip moves the scan position deltaPos bytes forward or backward 
within the flla It transfers no data 

XfeiRandom (whtahway. xReadWrite; pFlret- Ptr; ruitBytes: LONGINT; 
mode: TTOMode; Offset* LONGflsTT); OVERRIDE; 

whichWay is either )«eaa xwrite or xSkipi 

pFlrst points at the first byte to read data into or write data out 

of. It is ignored with xSkip. 

numBytes is the number of bytes read., written or skipped. 

mode is mtosotote, mRelatlve or mSequentlaL 

offset is a byte position from the beginning of the file when mode 

is irrtbsolute, or from the current filaposition if mRelatlve. 

XfexRandom reads/ writes or skips numBytes bytes of the file, 
starting at the Indicated position. All the other I/O methods call 
this method. XfeiRandom calls the Lisa OS directly. Reading 
and writing are always done left to right (from the beginning 
towards the end) regardless of the scanDirectlon. 

XferSequential MilchWay: XReadWrlte; pFlrst: Ptr; numBytes: 

IsTTEQERi OVERRIDE; 

wttchWay is either rftoad, xwrtte or xsklpi 

pFlrst points at the first byte to read data into or write data out 

of. It is ignored when wrichway equals xSkipi 

numBytes is the number of bytes read, written or skipped. 

XferSequential reads, writes or skips the next numBytes bytes of 
the flla Reading and writing are always done l eft to jlght (from 
the beginning towards the end) r eg a r dl e ss of the scarOirectlon. 

XferPString (wrtchWay: **eadWrite; pStn TPStringjfc 

vtftfchway is either xReatt xwrtte or xSkip. 
pStr is a pointer to a string to read or writa 

XferFlie reads a string pStr* from a file or writes it to a flla If 
vrttictiway is xReatt the destination string must be long enough. 
Tr«entire string or file is transferred, regardless of the current 
flleSoannBf jjostttoni 
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FAILURE CONDITIONS Reported as Lisa OS error codes In the field 

flleScanner.enoar. 



NOTES: 



1. A fUeScamer is used to access a stored data file, to scan it* and to 
manipulate its individual elements. 

2. Before you can use a fUeScamer to access g file, the file must be opened 

by TFilaOREATE. 

3. The Refhum variable is used by the ToolKit and the Lisa OS and should 
not be altered. 

4. The Actual variable contains the number of bytes of data most recently 
transferred to or from the file. It is the same as the number requested 
unless there is an error. In that case, fUeScamer-errar is greater than 
(zero). 

5. fUeScamer.error contains the code of the first error (or the first warning, 
if there was no error) encountered since the error variable was set to 0. 
Warning codes are negative; error codes are positive. 

6. The XfiBr methods are designed so that the same procedure may transfer 
data to or from a file, 

7. You may have more than one fUeScamer open on the same file at the 
same time. 

8. WARNING: No checking is done that sufficient space has been allotted for 
data reads at pFirst* or p5tr\ 

9. The application does not need to use TFUeScamer to read end write 
ToolKit document files; the application's docManager does that for you. 
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CLASS: THeadng 
SUPERCLASS: Tlmage 

DEFINED SUBCLASSES: none 
1«RTTED DATA FIELDS: 



DATA FIELDS: 



R extentLRect: LRect; The size of the entire Image. 
R view: TView; The view to which this header 

v or footer is attached. 
aiowMouseOutskte: BOOLEAN; 

Not significant for headings. 

printMenagen TPrintManager; The printManager for the view with 

which this heading is associated 

pageAilgnment: TPageAlignment; 

From the set: aTopLeft 

aTopOenter, aTopRkpvt, 

aBottomLeft* aBottomOenter, 

cBottomRkftt. 

The vertical and horizontal offset 

from the headings home edge or 

comer. See the notes below. 

If TRUE, this header or footer is 

printed only on odd numbered 

pay?s» 

If TRUE, this header or footer is 

printed only on even numbered 

pagg$, 

The first page to have this header 
or footer. 

The last page to have this header 
or footer. 



offsetFromrtignment: LPoint; 

oddOnJy: BOOLEAN; 

evenOnly: BOOLEAN; 

minPage: LONGINT; 
MBDPagp: LONGNT; 



METHODS: 



ChangBPageAUgvnent (hewPage/Ulgnment: TPageAUgnmentJ; 

newPageAlignment is a new value for headtagpageAltgnment 

THecdlno^crwngePageAlignmBnt Installs newPageAlignment as the new 
page alignment for the heading. 

AdJustFoKPaga (pageNumter: LONGaNT; eoltinp; BOOLE/*fc DEFAULT; 

pageNumber is the number of the page currently being prepared for 

printing. 

editing indicates whether or not this method is being called from the 

Headings and Margins dialog, or a similar application-defined dialog. 

THeadlngAdJuctFcHPage does nothing. You can reimplement it so 
that it makes any necessary modifications to the heading that should 
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be made before printing it on the given page. AdjustForPage is 
called Just before the heading is printed on the page. 

Draw; 

THeadlngJDraw draws the heading in the pageView. 

LaunchLayoutBox (view: TVtew> Hmage; 

view is a view in which layout will take place. 
The return value is an image, usually a layout box. 

THeacflngJ-aunchLayoutBox does nothing. If you want the user to be 
able to manipulate the hearings of the printed version of your view 
using the Headings and Margins dialog, you must redefine this 
method. The simplest way of doing so is to return 
TPageLayoutBoxCREATE (see the interface of UDialog for 
particulars). If you want editing to be possible, you need to define 
your own subclass of TPageLayoutBox, and have LaunchLayoutBox 
return and instance of that class. 

LocateOnPage (editing BOOLEANfc 

editing indicates whether or not this method is being called from the 
Headings and Margins dialog, or a similar application-defined dialog. 

You should never need to override this method. 
THeadtngLocateOnPage places the heading properly on the page. 

OffSetBy (deltaLPt- LPrtnQ? 

deltaLPt a vertical and horizontal change, expressed as a point 
relative to OHQl 

OffSetBy shifts the heading's extentLRect by the values given in 
deltaLPt If your subclass of THeading has data structures in it that 
use view-relative locations, you should redefine OffSetBy so that 
those locations get adjusted. Call SUPERSELF-OffSetBy after you do 
your application-specific offsets. 

NOTES 

L THeading defines header, footer, and margin Images for use in printing. 

2. ^plications rarely need to subclass or to refer directly to instances of 
THeading. 

3. Unlike with most images, headln^extehLRect only defines the size of the 
heading. The position of the heading is determined by 
heedingpegeAlignmBnt and heacflngxrffsetFromAiigrffwnt. 

4. The value in heacflngjjegeAllgnment determines. In general where on the 
page the headftg is located. A heading can have a pageAUgnment that 
puts the base point for the headtag at the top center, top left top right, 
bottom center, bottom left or bottom right of the page. The values 
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contained in offsetFromAligTment are used to offset the base point of the 
heading from the given pageAlignment point 

5. Where the base point of the heating is located depends on the 
pageAlignment point The base point is always the point in the heading 
coresponding to the pageAlignment point For example, if the 
pageAlignment is aTopLefl the base point of the heading is its top left 
comer. If the pageAlignment is aTopCenter, the base point of the heading 
is its top center, in effect, the pageAlignment defines a Justification. A 
pageAlignment of aTopCenter or aBottomCenter defines a heading that is 
always centered around the point defined by pageAlignment and 
offsetFromAlUpment A pageAlignment of aTopF&jtt or aBottomRiott 
defines a heading that has its right edge fixed, regardless of the length of 
the heading. 

6. Because pageAlignment defines a point on the edge of a page, and many 
printers cannot print on the edges of pages, a heading generally has a 
non-zero value in offsetFromAUgnment. 

7. headings can be determined dynamically, so their size can change from 
page to page. AdJustFarPaqe is used to get the heading's extent correct 
(and its contents as desired); LocateOnPage offsets the heading to the 
position on the page indicated by its pageAlignment offeetFromAlignment 
and extentLRect 

a. ToolKit applications generally use TLegendHeading, defined in the Dialog 
Building Block to produce heatfings. if you use that the user can use a 
menu command to call up a dialog box that allows definition of headers. 
TLegendHeading headings can only be one line long. See the 
documentation on the Dialog Building Block for more information. 
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CLASS: Tlmage 

SUPERCLASS: 
DEFINED SUBCLASSES 

Inherited data fields: 



TObJect 

TVIew 
THeadKng 



none 



DATA FIELDS: R extentLRect- LRect; 
R view: TVIew; 

ailOWMOUSeOLItSkte BOOLEAN- 



METHODS YOUR APPUCATTON MUST OVERRIDE: 



The bounding box of the entire 
Image, in view coonflnates. 
The view in which this image 
appears* 

FALSE by default When FALSE, 
and the mouse point is outside the 
image, the point is converted to the 
closest point within the Image. If 
TRUE, the point is not converted 
In that case, mouse points can be 
outside extentLRect and, 
particularly, can be negative. This 
feature exists primarily for use 
with sidebands. Note that your 
program must be prepared to handle 
mousepoints outside extentLRect 



CREATE (object: TObJect; heap: THeap; ltsExterfcLRect; ltsViev. TVIew): 
Tlmage; 

itsExtent is the size of the image. 

ItsVlew is the view in which this Image appears. 

TlmagaCREATE creates an object of type Tlmage. Normally, your 
application does not deal directly with Tlmage or Its methods; you 
need to subclass TVIew, and implement a CREATE method for your 
subclass. 



Draw; 



You should implement a Draw method in each descendan t of Tlmage 
to draw the Image. Your Draw method should assume that thePad is 
set up to draw in one pane. (See TPad in Chapter 3 for an 
explanation of thePad.) 
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MouseRelease; DEFAULT; 

You may write a MouseRelease routine that takes some 
application-dependent action when the mouse button is released. 
Tlmag&MouseRelease calls selectionMouseReleese. 

MouseTtaok (mPhase: TMousePhase; mouseLPt: LPointk (DEFAULT; 

mphase is the mouse state: mPress, mMove, or mRelease. 
mouseLPt is the view-relative point where the pointer is located. 

TimageJMouseTtaok dispatches mouse events to MousePress, 
MouseMove, or MouseRelease. 

ReactToPrinterChange; DEFAULT; 

ReectToPrinterChange is meant to allow an image to react to a 
change in the choice of properties of the printer for which the 
document is formatted. TlmageJReectToPrinterChange does nothing. 
(This method is implemented for you by TVIew.) 

RecalcExtent; DEFAULT; 

RecalcExtent is intended to instruct an image to recompute its 
extentLRect TlmagejRecalcExtent does nothing. 

Resize (newExtent: LRectfc DEFAULT; 

newExtent is the new Image size. 

Resize sets the extentLRect of the Image to newExtent 

SeesSameAs (image: Tlmage): BOOLEAN; DEFAULT; 

image is an object of type Tlmage or a descendant of image. 

The return value indicates whether or not Image is the same as SELF. 

Tlmage-SeesSameAs compares image with SELF. If they are the same 
object S e esS ameA s returns TRUE. You can re-implement 
SeesSameAs to return TRUE whenever you think that is sensible. For 
example, you might want to return TRUE if the two Images are 
derived from the same set of objects. 

FAILURE CONDITIONS: none 

NOTES: 

L You do not usually deal directly with Tlmage. You normally subclass 
TVIew and then use the subclass to create the application's view, or one 
of the application's views. 

2. An Image defines a portion of a view. 

3. The Image's extentLRect describes,, in 32-bit view coordinates, the 
bounding box of the portion of the view occupied by the Image. 
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Aside from the subclasses of Tlmage listed above, subclasses of Tlmage 
are used extensively in the text and dialog building blocks. Those 
subclasses include: TTextlmage and T P ar d mag e from the text building 
block, and 7Dialo#mage, TDialog, and a number of other dialog 
components from the dialog building block. See the documentation of 
those building blocks for more information. 
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CLASS: TUst 

SUPERCLASS 



TOoUectlon 



DEFINED SUBCLASSES: none 

INHERITED DATA FIELDS R Size LONGBNT; 



dynStart: INTEGER; 
hOieStart: INTEGER; 
holeSize: INTEGER; 
hdteSttt INTEGER; 



DATA FIELDS 



none 



The number of real elements in 
this list not counting the hole. 
This is a LONG3NT for the 
benefit of huge collections, such 
as remote data bases. It is 
always in the NTEGER range 
for Instances of TUst 
The number of bytes from the class 
pointer to the dynamic data area 
means hole at the begimirvp/alue 
of size means hole at the end. 
The initial size of the hole, 
measured in a number of members. 
How much to grow the collectiorr 
by if the holeStze goes to a 



METHODS: 



CREATE (objBCt TObJecf itsheapc THeap; WtialSiack: INTEGER^ TUst; 

InlttalSlack is the size of the initial hole, in member-sized units. 

TUstCREATE creates a new object of type TUst JnlUalSlack is a 
hole for list members. Because the list is created with a hole, the 
insert methods can be used to initialize the list without allocating 
any extra space. 

At (J: LONGN1> TObject DEFAULT; 

i is an ordinal position in the list 

The return value is an element from the list 

At returns the element at the given position in the list 
Subclasses generally override At 

Debug (numLevels: INTEGER; memberT>peStn S255fc OVERRIDE; 

numLevels is the number of levels of detail printed. 
memberTypeStr is only relevent for arrays. 

Debug is called by the ToolKit debugger to print details about 
this Ust numLevels determines how many levels of detail are 
printed. When numLevels is: 

(zero), the debugger prints Just the class of Ust 

1, the debugger also prints size of list 
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2, the debugger also prints a compacted list of member classes 

greater than or equal to 3, the debugger also prints class, size, 
and calls Debug(numLevei$-l) on members of the list 

Debuj^embers; 

Debu^lembers is present in debugging version only; it prints 
elements on the alternate screen., . 

OelAU (freeOld: BOOLEAN); DEFAULT; 

freeOld indicates whether or not the objects in the list are to be 
freed. 

CW/Ul deletes ail the elements of a list If freeOld is true, the 
objects to which the list element point are also deallocated by 
calling Free. The list Itself is not deleted. 

DelAt Q* LONGONT; freeOlfc BOOLEAN DEFAULT; 

i is an ordinal position in the list 

freeOld indicates whether or not the original object is to be 

deleted 

DelAt deletes the element at position L If freeOld is TPUE* the 
object to which the list element points is also deallocated by 
calling Free. 

DelFlrst (freeOld: BOOLEAN); 

freeOld indicates whether or not the object in the list is to be 
freed. 

DelFirst deletes the element at the beginning of the list If 
freeOld is TRUE, the object to which the list element points is 
also deallocated by calling Frea 

DelLast (freeOld: BOOLE/**); 

freeOld Indicates whether or not the object in the list is to be 
freed. 

DelLast deletes the element at the end of the list If freeOld is 
TRUE, the object to which the list element points is also 
deallocated by calling Frea 

DelManyAt 0= NTEGER; howMany: INTEGER; freeOld: BOOLEAN); 
DEFAULT; 

i is an ordinal position in the list 

howMany indicates the number of list elements to be deleted. 

freeOld indicates whether or not the objects in the list are to be 

freed. 

DelManyAt deletes a number of elements from the list The first 
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deleted element is at position L If freeOld is TRUE, the objects 
to which the list elements point are also deallocated by calling 
Frea 

DelObJect (object: TObJect; freeOlds BOOLE/*fc 

object is an object 

freeOld indicates whether or not the object in the list is to be 

freed. 

DelObJect deletes all occurrences of object in the list If fFree 
is TRUE, the object is deallocated by calling Free. 

Each (PROCEDURE DoToObjBCt(0bjBCL- TObjBCtfc OEFAULT; 

DoToObJect is a PROCEDURE that takes an object as its 
argument 

Each applies the given PROCEDURE to each element in the list 
First- TObjBCt; DEFAULT; 

First returns the first element in the list 

msAt (k INTEGER; Object TObJect) ABSTRACT; 

i is an ordinal position in the list 
object is an object 

msAt inserts an element in the list The newly inserted element 
occupies position L 

InsFirst (object TObjBCtfc DEFAULT; 

object is an object 

InsFirst inserts an element at the beginning of the list The 
newly inserted element occupies the first position in the list 

InsLast (object TObJectfc 

object is an object 

msLast inserts an element at the end of the list The newly 
inserted element occupies the last position in the list 

Last: TObJect; DEFAULT; 

Last returns the element at the end of the list 

MBIiyAt CL howMany: LONGaNTJt TLiSt; 

1 is an ordinal position in the list 
howMany is a number of elements. 

ManyAt returns a list with the elements from the original list 
beginning at position I and continuing through howMany elements. 
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MemberBytes: INTEGER; 

MemberBytes returns the amount of space, In bytes,, taken up by 
each element in the list As lists contain only handles, this 
method always returns 4. (This method is more useful in other 
types of collections.) 

PopLasfc TObjBCt; 

Pop returns the element at the end of the list and then deletes 
that element from the list etement-SELFPopLast is equivalent 
ta 

popLasfe- SELF JLast* 
SELFjDelLastfALSEk 

Pos (after; LONGBNT; object: TObJectfc LONGUNT; 

after is an index number in the list 

object is an object that might be in the Ust 

The return value is the index number of object or, if object is not 

found after. 

Pos searches the list from after to the end. If object is found the 
index number of object is returned. To seach the entire list use 
after of (zero). 

PutAt (k LONQWT; Object TObjBCt fteeOW: BOOLE/*$ DEFAULT; 

i is an ordinal position in the list 

object is an object handle. 

freeOid indicates whether or not the original object is to be 

deleted 

PutAt deletes the element at position i and replaces it with 
objBct If freeow is TRUE, the object to which the original list 
element points is deleted Subclasses generally override PutAt 

Scanner. TUstScamer; 

The return value is a UstScanner for this list 

Scanner returns an object of class TUstScamer, allowing use of 
listScamer methods. This is equivalent to 

listSc a merF r o m Ct scanForwanfc 

ScannerFrom (firstToScart LONGDsTT; scanDirection: TScanDlrectionJc 
TUstScamer; DEFAULT; 

firstToScan is a position in the list 
scanDirection scanForward or scanBackWard 
The return value is a new arrayScamer. 

ScannerFrom returns an object of class TUstScamer, with 
UstScamerPosition equal to firetToScan minus one (or plus one, if 
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.the scarOrectlon is scanBackwan& so that the first call to 
listsoanner^oen returns the address of the record at flrstTosoan. 

StartEdU (withSlack: INTEGER); 

withSlack Is the new value for hdlestdL 

StartEdlt changes the value of hoteStd to withSlack so the next edit 
call creates a hole of size wltf&pcK, so that subsequent edit calls 
act more quickly. 

StopEdlt; 

StopEdtt removes the hole from the list and sets holeStd to (zero). 
Any subsequent edit call removes any hole it forms. 

FAILURE CONDITIONS Heap cant grow. 

Object size > 32K bytes. 
Deleting from an empty list 
Subscript out of range. 

NOTES: 

1. This defines all lists of objects used in the ToolKit 

2. It is faster to traverse a list using Each than it is to use a iistScamer. 
However, insertion and deletion are not possible during traverses using 
Each. An example of proper use of Each to traverse a list is: 

function PeelQoo(Bar«ras(ltuwtt TLtetfc 

FUNCTION QoodBanara(ob> TObjectfc 

VAR banana TBanana; 
BEGIN 

banana- TBananafobJt 

If bananagood THEN bananaPeel; 
END; 

BEQW 

burictcEachfQoodBanena]^ 
END; 

3. lists have three modes: create mods eat mock and static mode 

4. When you first create a list it is in create mode. You define an 
WtialSlack value in the CREATE calL The list is given enough empty 
space to hold irdtiaisiack object-references. That space is the hole. As 
you add members, the space In the hole is used for the new 
object-references. Tne amount of space allocated to the list does not 
change until you fill up the hole with object-references. You can also 
call UstStopEcflt which removes the hole from the list 

5. When the hole is filled the list enters static mode. In static mode, no 
hole is ever maintained. If you add a member, the list is copied into a 
space large enough to hold the object-reference for the additional 
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member.. If you delete a member, the extra space is freed. 

6. Enter edit mode by calling llsLStartEcflt(wltnsiack). In edit mode, a hole 
big enouji for witnSlack object-references is initially created As you 
add members, the size of the hole de c rease s . When the hole is entirely 
filled, the space allocated to the list is increased, so there is a new hole 
big enough for witnSlack object-references. If you delete members, the 
extra space is added to the hole, call U$LStopEdit to stop editing. Any 
space taken up by the hole is then freed. 
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CLASS: TUstScamer 

SUPERCLASS TScamer 



DEFINED SUBCLASSES: none 



WHERITED DATA FIELDS 



R 
R 



collection: TCoUection; 
position: LONG3NT; 



R inc re ment- INTEGER; 



scanDone: BOOLEAN; 



R atEnds BOOLEAN; 



rxilMUIJa: 



The list being seamed. 
The current position of 
the scanner. The scanner 

position is always 
between bef ore, or after 
members: o-before first, 
sizen-after last 
The change in position 
for every scan: l if 
scanning forward, -l if 
scanning backward. 
When this is TRUE, the 
next Scan call returns 
FfiLSE, signalling the end 
of the scan. The VW 
parameter of the scan 
method, which normally 
contains the next object 
in the list, is unchanged 
after the Scan call. 
TRUE if the end of the 
list is eminent, so that 
the next Scan call will 
return F^-SE. 



CREATE (object: TObJect; itsUst: TUst; ItsWtlalPosittori LONGINT; 
ItsScanDirectiort TScarCftrectton): TUstScamer; 

itsList is a list object 

itsinlUaiPosltion is the initial ordinal posiUon in the list 

itsScanDirection is see/Forward or scanBacKward. 

TUstScamer-CREATE creates an object of type TUstScamer, 
which is used to access itsList itsUst must exist before a 
listscamer can be created for it; however, you can use a 
TUstCREATE call in your TUstScame&CREATE call, which will 
create the necessary list object 
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/^pend (object- TObJect); DEFAULT; 

object is a new member of the list 

/^jpend adds object to the list Immediately after the current 
position, position is adjusted by adding 1, so that the next Scan 
returns the object after the new object 

Delete (freeOMb BOOLE/*fc DEFAULT; 

freeOld indicates whether or not the object deleted from the list 
is to be freed. 

Delete deletes the object at the current position, position is 
adjusted by subtracting L 

DeleteRest (freeOld: BOOLEAIsfc DEFAULT; 

freeOld indicates whether or not the objects deleted from the list 
are to be freed. 

Delete deletes all objects after the current position, position is 
unchanged. 

Done; DEFAULT; 

Done signals that you are finished using this listScanner. The 
next call to ll$tscanner.scan returns FA-SE, as if the end of the 
list had been reached, unlike when the end of the list is reached, 
however, the returned object in Scan remains unchanged. 

Free; OVERRIDE; 

Free deallocates this listScanner object 

Obtains TObjBCt; DEFAULT; 

"me return value is a object from the list 

Obtain returns the current object without advancing position. 

Replace (Object: TObjBCt; freeOld: BOOLE/Ysfc DEFAULT; 

object is a object that replaces the current object 

freeOld indicates whether or not the object deleted from the list 

is to be freed 

Replace removes the current object from the list and replaces it 
with the given object The new object is now the current object 

Scan (Wft nextOb* TObJBCtJt BOOLEAN; DEFAULT; 

nextObJ is the next object from the list 

The return value is FALSE if the end of the list has been reached 

or UstScamerDone has been called. 

Scan begins at the beginning of the list (or the end if 
scanDirection is scanBaokwatf) ana each time it is called returns 
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the next object me returned object is referred to as the current 
object The value of Scan is TRUE until Scan is called after the 
last object in the list is reached or until UstScamerDone has 
been called. If the end of the list was reached, and Done was not 
called, the value of nextdbj is NIL. If Done was called, nextObJ 
keeps the last value it had. When method Done is called or when 
the scanner reaches the end of the list the scanner is freed the 
next time listscamerjscan is called. 

Seek (listPos: LONGING 

listPos is the location to which you wish the scanner to move. 
listPos - is the beginning of the list 

Seek moves the current scan position to listPos. It transf en no 
data 

Skip (deltaPos: LONG8NT); 

dBltaPos is the number of bytes you wish the scan position to 
move within the list A positive value moves the position toward 
the end of the list' a negative value moves the position toward 
the beginning of the list 

Skip moves the scan position deltaPos elements forward or 
backward within the list It transfers no data 

FAILURE CONDITIONS: Attempt to insert delete or replace after a delete has 

occurred at the same position. 

NOTE& 

1. A UstScamer is for moving throucp a list and manipulating the individual 
elements, list objects are created through class TUst 

2. You never allocate a scanner directly; one is allocated when you call 
list-Scanner. 
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CLASS: TMarglnPad 
SUPERCLASS: TPafl 

DEFINED SUBCLASSES: none 

INHERITED DATA FIELDS: See TPadL 
DATA FIELDS: R View. TVlew; 

R pageNumben LONGINT; 

R bodyPact TBodyPad; 



NOTES: 



The view to which this marginPad 

relates. 

The page of the view that prints 

with this marginPad. 

The bodyPad containing the 

printable version of the body of the 

page. 



l. 



2. 



A marginPad is the output port for page headings and other page 
adornments that are printed on a page on the printer or displayed in the 
image of a page in page preview mode, 

/^plication programs usually do not need to subclass or otherwise deal 
with TMarglnPad. 
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CLASS: TMenuBar 
SUPERCLASS: TObJect 

DEFBsED subclasses: none 
INHERITED DATA FIELDS: none 

DATAFELDS: lsLoadEXfc ARRAY [LiUBtflBriJS] OF BOOLE/VM; 

* Each element is TRUE if trie 
corresponding menu has been 
inserted into the menu bar. 

mapping TAnay; Relates command numbers to menu 

and item indices. 

numMenus: INTEGER; The number of menus used by this 

application. 

numOommands: DMTEGER; Total number of commands in all 

the application's menus. 

METHODS YOUR APPLICATION MIGHT CM±1 

BuUccmtfvfame (ctes tcrna ^ 

destcmd is the number of a command in one of the menus, if 

destCmd does not exist this method has no effect 

tempiatecmd is the command number associated with a command 

name template. If tempiatecmd does not exist this method has no 

effect 

param is a pointer to a string, or NL- 

BulidCmdName replaces the string associated with destcmd with a 
new command name built with the string pointed to by param and the 
template associated with tempiatecmd. tempiatecmd corresponds to 
a string in a menu of the farm: 

text * tempstring * moretext 

where text and moretext are optional. (If moretext does not exist 
you do not have to give the second carat) tempstring is replaced 
with the param string. The carats Q are removed and the resulting 
string is placed in the position in a menu corresponding with 
destCmd. If param is NL, the carats are removed, tempstring is left 
alone, and the resulting string is put in the menu. 

Check (cmdNumben TCnvriuritsr; diecKedc BOOLE/V^ 

omdNumber is the number of a command in one of the menus. 
checked is whether (TRUE) or not (FALSE) the command should be 
checked off. 

Check puts a check in a menu next to the command corresponding to 
cmdNumber. According to the User Interface 5Esr»fera$ the check 
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indicates that the item i$ presently in force. The ToolKit does not 
verify that the command should be checked. 

Delete (menulCfc INTEGER); 

menulD is the identification number for one of the application's 
menus. 

Delete removes the menu from the menu bar. 

Draw; 

Draw draws the menu You should call this method after you call 
menuBar Jnsert or menuBarJDeleta 

Enable (cmdNumber: TCmdNumtwr; canBeChosert BOOLEAN); 

cmdNumber 1$ the number of a command In one of the menus. 
canBeCtosen is whether the command should be enabled (TRUE) or 
disced (FALSER 

Enable determines whether or not the user is allowed to choose the 
command corresponding to cmdNumber. When a command is 
disabled, it appears in dim type in the menu, and the user cannot 
choose it When a command is enabled the command appears in 
normal type, and the user can choose it The ToolKit does not make 
certain that the command should be enabled or disabled. 

EndCmd; 

EndCmd removes highlighting from the menu bar. See 
TWar*£arJH©fflgfitMeru 

QetCmtfslame (cmdNumben TCmdNumber; pName: TPStringfc BOOLEAN; 

cmdNumber is the number of a command in one of the menus. 
pName is a pointer to a string location for the command name, or 
NIL, if you do not want to find out the command name. 
The return value indicates whether or not the command was f ouna 

QetOmdName checks to see if cmcNumber corresponds to an existing 
conm a n a if it does, the return value is true, in additioa if 
pNeme is not ML* QetcmdName puts the command name that 
c orrespond s to the co m ma n d number in the location pointed to by 
pNama 

For example: 

WAR x5255; pefines a variable for the command name.) 



menuBaff -QetOmdName (cmcfslumber, ©xjc 
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rtfrfllgWMenu (wlthCmdfc TOrtiNtnttei); 

witncmd is the command number of the menu command you are 
about to process. 

HtyflfyfttMenu hl<jttl#ts the title of the menu containing the given 
command. The TooiKit does this for you when the user chooses a 
command from a menu, uses an Apple key command, or uses a clear 
key command. You only need to jcall this method when the command 
was from somewhere else. First call menuBarMc^l^tMenLL Then 
call TWindowJDoCommand to do your comman d , rather than creating 
the command object and calling commandLPerfdrm yourself. 
TWindowJDoOommand turns of f highlighting when the command is 
finished processing. If you do not call TWindowrtoCommand, call 
menuBar.EndGmd when you are finished processing the command; that 
turns off highlighting. 

Insert (rnenUBD, befraelDt WTEGER); 

menuID is the identification number for one of the application's 
menus that is not presently in the menu bar. 
befdreE) is the identification number for one of the menus in the 
application's menu bar. 

insert inserts the menu in the menu bar so that it appears 
immediately to the left of the menu Indicated by beforeED. if 
beforeBD is 0, the menu is placed at the end to the right of all other 
menus in the menu bar. 

PutCmdName (cmdNumben TOnoNumber; pName: TPStrtngit 

cmdNumber is the number of a command in one of the menus. 
pName is a pointer to a string location holding the command name. 

PutCmdName replaces whatever is in the menu that corresponds with 
cmdNumber with the string pointed to by pName. 

unload; 

unload removes the application's entire menu bar. 



NOTES: 



1. There is only one instance of TMentear for any document,, and that 
instance, accessed by the global variable menuBar, is created by the 
TooiKit 

2. you never subclass TMenuBar. 

3. The menuBar controls the application's menus. 
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4* The methods given here are sometimes called from wtrtiow-SstUpMenus, 
window JDartDoCommand and selectioaCartDoCommand. Otherwise, you 
probably will not deal with this class. 

5. These methods change the menu or menu bar until either another menuBar 
method effects another change, or a new process is created for the 
application Remember that, unless you define your application to manage 
only one document, all documents belonging to a single application share 
the same process. Since every process has only one menuBar object, these 
methods change the menu bar for all documents using this process, in 
addition, since the process generally remains until the Lisa is powered off, 
even if there are no active documents using the process, you should be 
careful that the menu bar is in the correct condition when it is displayed 



11-72 



Usa TooiKIt Reference Manual Part U Class Reference Sheets 

CLASS: TODJect 

SUPERCLASS ML 

DEFINED SUBCLASSES: All other classes are descendants. 

INHERITED DATA FIELDS: none 

DATA FIELDS none 

METHODS 

CREATE (Object: TObJect- heap: THwtfc TObJect" ABSTRACT; 

TObjBctCREATE is an ABSTRACT method and does nothing. 
Each subclass of TObJect has its own CREATE method. 

Become (ob£ TObJectfc 

obj is an object-reference. 

Become frees the calling object by calling object-Free, and reuses 
the object's handle by making it to refer to obj. For example, 
refl£ecomeCTMyObJectCREATE(objBct heap) frees the object 
pointed to by reft and makes refl point at the new object All 
references to refl now refer to the new object 

Class: TCiass; 

Class returns the class pointer for this object's class. 
Clone (heap: THeapJt TObJect; 

heap is the heap for the new object 

Clone should create a copy of the object and all its subordinate 
objects, on heap and returns a handle on the new object 
TObJectClone Just calls doneObJect which copies only the object 
itself. Override Clone to copy subordinate objects. 

doneObJect (heap: THeepJt TObJect; 

heap is the heap for the new object 

CloneObJect allocates a copy of the object on heap and returns a 
handle on the new object Overriding is rarely necessary. 

Convert (fromVter sl ort Byte); ABSTRACT; 

fromvters l on is the old object's version number. 

Convert is intended to update an object to the current version of 
the object 
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Debug (numLevels: INTEGER; memderTypeStjrin^ S255fc (DEFAULT; 

numLevels is the depth of detail printed. 

Debug, present only In the debugging version of the ToolKlt* prints 
details about the object on the alternate screen, it is called by 
the debugger in conjunction with the Fields method. When 
numLevels is equal to (zero). Debug prints only the object's 
class. When numLevels is equal t$ 1, Debug prints the object's 
class, and the name, class Of any) and value of each field. When 
numLevels is 2, Debug prints all the information printed for 
numLevels- L and also prints the same information about objects 
referred to by the fields of the original object As the value of 
numlevels increases, additional levels of class reference fields are 
detailed, overriding of Debug is rarely necessary. 

Fields (PROCEDURE Ftektrameftvnype: S255fc DEFAULT; 

Fields Is present in the debugging version of the ToolKlt only. At 
the present time (TK 8e), if you want the ToolKlt debugger to be 
able to display the fields of your objects, you must define this 
method for every class you create. See Chapter 2 for information 
on writing Fields methods. 

Free; DEFAULT; 

object-Free should free object and all objects subordinate to 
object TObJecLFree simply calls FieeObjBd which frees object 
and nothing else. If you create a descendant of TObJect that has 
suborcttate objects, you should override Free to free the 
subordinate objects. End your routine by calling 
SUPERSELFJFREE 

FreeObJecf DEFAULT; 

FreeObJect removes the associated object and deallocates the 
heap space used by that object Overriding is rarely necessary. 

HeaprTHBep 

Heap returns the heap this on which this object Is stored. Never 
override this method. 

HBQpBytes: INTEGER; 

The return value is a number of bytes. 

MeepBytes returns the number of bytes used by the object in the 
heap. 
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Reed(s: TStringscamer); 

% Is a stringscamer. 

Reads the data in the object without the object's class pointer or 
the dynamic part if any, by using the stringscamer to get the 
object's data 

Write (s: TStringScamerfc 

s is a stringscamer. 

Writes the data in the object without the object's class pointer 
and any dynamic part 

Joinciass (newClass: TClass> TObJecf 

newClass is the object's new class pointer. 

Joinciass converts the object to a new class. It is called for 
you when version conversion is required. 

FAILURE CONDITIONS: Heap cant grow. 

Object freed twice. 

Tried to do xJBecome(y) when x and y were not on the 
same heap. 

Tried to do xJoinClass(newCla5$) when the class of x and 
newClass are unrelated 

NOTES 

1. Class TObJact is the ancestor of all other classes. 

2. Instances of TObJect are never created. 

3. All objects are instances of descendants of TObJect 
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CLASS: 



TPad 



SUPERCLASS: 
DEFINED SUBCLASSES: 



TAI88 



TPane 

TBodyPad 

TMarginPad 

IM-ERITED DATA FIELDS ImerRect: Recfc 



DATA FIELDS: 



GrafPort-ielatlve bounds 
^excluding borders. 
GrafPort-relative bounds Including 
border. 
uaienlBiaUt TBranchAree; 

Not relevant for 



outeiRect: Red; 



port: QrafPtr; 
vlewedLRect: LRect; 

vlsLRect: LRect; 

avaULRect: LRect; 

scroUOffset- LPolnt; 

origin: Point; 

cdOffset LPotat; 

cllppeoRect: Rect; 

padRes: Point; 

viewedRes: Point; 

seated: BOOLEAN; 

sceJeFaotoR TScaier; 



The grafPort used by this pad. 

The portion of view that Is 

displayed in ImerRecL 

vlewedLRect sect visRgn while 

focused. 

The larger part of view that fits -in 

a grafPort coordinate Rect 

The distance scrolled from the view 

topLeft 

What to set the grafPort origin to 

vrtien focused. 

What to subtract from coordinates 

to get grafPort coordinates. 

Additional clipping to apply when 

focusing. 

The pad's resolution, expressed as 

spots/inch in the pad coordinate 

space. 

The view's resolution, expressed as 

spots/Inch in the view coordinate 



TRUE indicates that the 
scBleFactor is not 1, which means 
that coordinate scaling must be 
used. 

The net scale factor, combining the 
effects of zooming and the 
different coordinate systems of the 
pad and its view. 
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zoomFacton TScater; The zoom factors; The two zoom 

factors, one for vertical zoom and 
one for horizontal zoom, are stored 
as two Points, one of which holds 
the numerators, and the other the 
denominators of the zoom factors. 

METHOD YOUR APPLICATION MUST OvERRREJB 

create (object: TODJect; ltsHeepe THeap; itslnneiRect: Rect; 

ltsVlewedLRect: LRect; ItsPadRes, itsVtewRes: Point; ItsPort: 
GrafPtifc TPexfc 

ItslnneiRect is the window-relative bounds excluding the border. 

itsVlewed-Rect is the portion of the view visible in the pad. 

ItsPadRes is the resolution of this pad. 

itsVtewetff^es is the resolution of the view, or other 32-bit space, 

looked on by this pea 

itsPort is the grafPort. 

TPaHCREATE creates an object of type TPadL 

METHODS YOUR APPUCATION WILL C^-L: 

InvalLRect (n LRectfc 

r is the rectangle to be redrawn. 

TPadJnvalLRect forces a redraw of r at next call to window.Updata 
r is in view coordinates. 

InvalRect(n Rect); 

r is the rectangle to be redrawn. 

TPadJnvalRect forces a redraw of r at next call to wtndowjjpdata r 
is in grafPort coonflnates. 

setPen (pen: Penstatefc 

pen is a pen state. See the QuickDraw documentation for the 
available pen states. 

TPa&SetPen sets the pen state. 

SetPenToH^li^it (^Transit: THIfriTtansltk 

Ntfmansit is the change in highlighting of the displayed object The 
standard choices are: hNore, nOffToDtot rofrrooa hDtavraon, 
tOimToOff, MOnToOff, and hOnToDim. 

TPedJSetPenToHkytiky* sets the pen to the state appropriate for 
applying the indicated highlighting. 
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The following methods map coordinates from grafPort to view. 

DtetToLDIft (dlsUnPort: Point; V/« OistlnVtev: LPolntfc 

dlsUnPort Is a distance In grafPort coordinates. 
OsUnVlew Is the distance converted to view coordinates 

TPadDtstToLDist converts a distance in grafPort coordinates to view 
coordinates. 

PatToLPat ftwtlhPart: Pattern; V** Pattivlev: LPatterrfc 

patlnPort Is a pattern In grafPort coordinates 

lPatlnView is the same pattern converted to view coordinates 

TPadPatToLPat converts a pattern from grafPort to view coordinates. 

PtToLPt (punPort: Point; VAR PUrtVtew: LPointfc 

purport is a point in grafPort coordinates. 
IPttoVlew is the point converted to view coordinates. 

TPadPtToLPt converts a point from grafPort to view coordinates. 

ReotToLReot (reotinPort: Root; VfiR iRectWVtew: UReotfc 

rectlnPort Is a rectangle in grafPort coordinates. 

lRectmvtew is the same rectangle converted to view coordinates. 

TPattRectToLRect converts a rectangle from grafPort to view 
coordinates. 

The following methods do coordinate mapping from view to grafPort 

LDistToDlst ODlstlnVlew: LPalnt; VW dlsUnPort: Pointy 

IDistmview is a distance in view coordinates. 

dtetlnPort is the distance converted to grafPort coordinates. 

TPadLLDistToDist converts a distance in view coordinates to grafPort 
coordinates. 

LPatToPat OPatmvtew: LPatterru VAR petmPort: Pattern); 

iPattMew Is a pattern. 

patlnPort is the pattern converted to grafPort coordinates. 

TPalLPatToPat converts a pattern from view to grafPort coordinates. 

LPtToPt QPtHVtew. LPoint; VfiR ptlnPort: point* 

IPtmview is a point in view coordinates. 

ptlnPart is the point converted to grafPort coordinates. 

TPattLPtToPt converts a point from view to grafPort coordinates. 
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LRectToRect QRectlnvlew: LRect- V/« rectlhPart: Rectfc 

fftectmview is a rectangle in view coordinates. 

rectlnPort is the same rectangle converted to grafPort coordinates 

TPadLRectToRect converts a rectangle from view to grafPort 
coordinates. 

TT» following method is used by the ToolKit to move the pad within the 
view. 

OffsetBy (deltaLPt: LPoInt); 

deltaLPt is this 

TPadLOffsetBy offsets viewedLRect — no effect on display. 

The following method is used for display. 

Focus; OVERREe; 

"TPadFocus sets the grafPort so that subseque n t QuickDraw calls are 
correctly sent to this pal 

The following methods perform drawing, and allow coordinates to be 
expressed in view coordinates. They function, for the most part by 
converting the coordinates to grafPort coordinates, then invoking the 
corresponding QuickDraw call. 

DrawLArc (verb: Qrafverb; n LRect; startttigie, arc/>ngle: INTEGER); 

verb indicates what to do with the arc (frame, paint, erase, invert, 

mix 

r is the bounding box of the arc. 

startAngie is the angle of the start of the arc. 

arotagie is the angle of the arc. 

TPaHDrawLArc draws an arc in the view. 

DrawLBits (vw sicBlts: BltMap; vw srcRect- Rect v/« dstLRect 
LRect; mode: BMTEQER; maskRgrt RgnHandtet 

src6its is a bitmap, part of which is copied to this pad 

srcRect is the area in srcBits copied to this pad. 

dstLRect is the part of this pad that receives the copy from srcBits. 

modB is the transfer mode used to draw in dstLRect See the 

QuickDraw documentation for a discussion of transfer modes. 

matfcRgi is a region in this pad (presumably part of dstLRect) that is 

to be u nchange d by this drawing operation. 

TPadDrawLBits converts dstLRect to grafPort coordinates, and then 
ceils QuickDraw's StdBit procedure. See the QuickDraw 
documentation for more information. 
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DrawLUne (newLPt: LMnft 

newLPt 1$ the point to draw a line to. 

TPadDrawUJne draws a line. 

DrawLO/al (verb: GrafNterb; n LRectJt 

verb Indicates what to do with the oval (frame, paint, erase, invert 

fill). 

r is the bounding box of the oval 

TPadDrawLOval draws an oval in the view. 

DrawLPicture (pic: PicHandte; rdLRectfe 

pic Is a pointer to a QuickDraw picture. 

r is the desired bouding box, in view coordinates. 

DrawLPicture draws the picture pointed to by pic in r. See the 
QuickDraw documentation for a discussion of pictures. 

DrawLRect (verb: GarafVarb; r LRectfc 

verb indicates what to do with the rectangle (frame, paint, erase, 

invert, flll)t 

r is the rectangle to draw. 

TPatiDrawLRect draws a rectangle. 

DrawLRRect (verb: GrafVerb; n LRect ovalWldth, ovaHel^rt: INTEGERS 

verb indicates what to do with the roundrect (frame, paint, erase, 

invert fill)i 

r is the bounding box of the round rectangle. 

ovalWkJth is the width of the oval 

ovalHeicfit 1$ the height of the oval. 

IPadDrawLRRect draws a roundrect in the view. 

DrawLText (textBuf: Ptr; startBytes, numBytes: INTEGER); 

textBuf is a pointer to text 

startBytes the starting location in textBuf*. 

numBytes the number of bytes. 

TPadDrawLText draws text scaling according the the current zoom 
factor, if n ecessary. 
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OTHER METHODS 

ChUdWithPt (pt: Palnfc crtldList: TUst; WR nearestPt Point): TAre* 

pt is a point in window-relative coordinates. 
chiidList is a list of areas contained within this pal 
nearestPt is the point in the returned area closest to pt 
me return value is one of the areas from chiidList 

ChildWithPt first finds the point M\ joUmerRect closest to pt it 
then comp a re s the new point to the outeiRects of all the areas in 
chiidList When it finds the area that contains the point it finds the 
point in that area's ImerRect that is closest to the point That value 
is returned as nearestPt The area containing nearestPt is the return 
value. 

CllpFurtherTo ftBancfc Rectfc 

iBand is a rectangle, in grafPort coordinates. 

CUpFurtherro narrows down the clip area at the next call to Focus. 
This method is used internally by the ToolKlt 

Redefine OtsmnerRect Rect; ItsVlewedLRect- LRecf ItsPadRes, 

ItsVlevrttes: Point; ItsZdomFacton TScaler; itsPort GrafPtr): 
TPafc 

itslnnerRect is the window relative bounds excluding the border. 

ItsVlewedLRect is the portion of the view seen through this pal 

itsPatftes is the resolution of this pad. 

itsViewRes is the resolution of the view looked on by this pal 

itsZoomFactor is a zoom factor for the pal 

itsPort is the grafPort 

TPalRedeflne is used to change the properties of a pad without 
having to free the old one and create a new one. in effect this 
allows re-use of an allocated pal with any or all of its parameters 
c hange d. 

Reslzeinskte (hewlnnerRect: Recti 

newmnerRect is the pad bounds excluding borders. 

Resizelnside changes the size of padJmerRect It performs 
higher-level operations on the pact such as resizing areas contained 
within this pal and then calls SELF-SetmnerRect 

ResizeO ut side (jnewOuUflRBbt: Reel); 

newOuteiRect is the bounding box 

ResizeOutside changes the size of paioutarRect it performs 
hicfier-level operations on the pal such as resizing areas contained 
within this pal and then calls SELF.SetOuteiRect 
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SetScnfllOffset (V/\R newOffcet: LPolrtfj; 

hewOffset is a new offset factor, with a vertical and horizontal 
compone n t Although this is a VflR argument, its value is not 
changed. 

TPaOSetScroUOffset recalculates padorigln and padcdOffset 

SetZdomFacUnr (zoornNLinerator, zoomOenomlnaton Point); 

zoomNumerator is a set of two numbers that form the numerator of 
the zoom factors. 

zoomDenomjnatar is a set of two numbers that form the denominator 
of the zoom factors. 

TPadSetZoomFactor changes the zoom factors of the pad. 

NOTCS: 

1. Methods of TPad fall into two categories: 

a) Those that convert coordinates between view and grafPort systems. 

b) Those that draw either to the screen or to a printer. 

2. You never create instances of TPad, and you rarely create instances of 
descendants of TPadL 

3. in general the ToolKit creates instances of de sc endants of TPad in order 
to draw on the screen and print for you. 

4. Panes, marginPads, and bodypads are instances of descenda n ts of TPad. 
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CLAS& TPageVtew 
SUPERCLASS: TVteW 

DEFINED SUBCLASSED none 
BM-CRITED DATA FIELDS: See TVtew. 

DATA FEUDS: none 

hCTHODS: None that are important for applications. 

NOTESt 

1. TPageVlew is used for the view associated with a marginPad when printing 
or previewing pages. (The application's view is associated with the 
corresponding DodyPad.) 

Z TPageVtewDraw is ejected to draw the headings on a page. 
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CLASS: TPaginatedVlew 

SUPERCLASS: TVteW 

DEFINED SUBCLASSES none 

INHERITED DATA FIELDS: See TVtew. 

DATA FIELDS R unpaglnatedVlew: TVlew; The view of which this is the 

paginated version. 

R pageSize: /V^RAYIVHSeiect] GF'LONQINT; 

The size of one page in the 
paginated view, in view coordinates. 

R worklnglnMarglns: BOOUEAN; If TRUE, the application (in its own 

sifcclass of TPaginatedVlew) is 
currently fielding events in the 
margins of the page, rather than in 
the body. 

METHODS: None that are important to applications. 

NOTES: 

1. applications normally do not need to subclass or otherwise directly 
concern themselves with TPaginatedVlew. 

2. There may be a different object of type TPaginatedVlew for every view 
used in the application. 

3. A TPaginatedVlew object is created when the user asks to preview pages. 
When that happens, the view's printManager*s Nev^aginatedView method is 
called to launch the paginatedView. Because NewPaginatedView is called 
to create the paginatedView object, you can subclass TPaginatedVlew. 
One reason you may wish to do so is if you want to allow concurrent 
editing of headers, footers and main views, as is done in Lisawrite's 
Preview Pages mode. 
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CLASS: TPane 

SUPERCLASS: TPad 

DEFINED SUBCLASSES: TMarglnPad 

TBodyPaa 

INHERITED DATA HELDSb See TPexL 

DATA FIELDS: R currentVIew: TVlew; The view displayed in this pane. 

R panel: TPane); Hie panel containing this pane. 

METHODS YOUR APPLICATION MAY CALL: 

CWldWIthPt ft* Point' crtldLlst: TUst; V/« nearestPt: Poinft TArea; 

pt is a point in pane-relative coordinates. 
oMKUst is a list of areas contained within this pane. 
nearestPt is the point in the returned area closest to pt 
The return value is one of the areas from ortidList 

CrtldWithPt first finds the point in paneJmerRect closest to pt It 
then the compares the new point to the outeiRects of all the area* 
in ohUdist When it finds the area that contains the point it finds 
the point in that area's imerRect that is closest to the point Tnat 
value is returned as nearestPt The area containing nearestPt is the 
return value. 

ScroUBy (V/>R deltaLPt LPoimfc 

deltaLPt is the amount of vertical (deltaLPtv) and horizontal 
(deltaLPth) scrolling desired in view coordinate units. 

ScrollBy scrolls the pane by the distance given in deltaLPt The 
scroll thumbs are moved accordingly. 

ScnfllToReveal (VAR anLRect: LRect; hNttnToSee, vMknToSee: INTEGER* 

anLRect an rectangle in the view. 
hMJnToSee a horizontal distance, in view units. 
vMinToSee a vertical distance, in view units. 

ScroUToReveel scrolls the pane so that some part of anLRect shows 
in the pane. WlnToSee and vMfaToSee define the minimum part of 
anLRect that is displayed after the scroll 

NOTES: 

1. TPane defines regions of the screen that display application data 

2. Applications never need to subclass TPane., end they also never create 
panes themselves. 

3. The ToolKit creates at least one pane whenever a new panel is created, or 
when the user splits existing penes with a split control 
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4* Panes occupy the region inside the borders of panels. Any part of an 
application view that is displayed is displayed In a pane. 

5. Several panes may look on a single view. Every pane that looks on a 
particular view is normally contained in the same paneL Every pane in a 
particular panel looks on the same view. 
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CLASS: TPanel 

SUPERCLASS TArea 

DEFINED SUBCLASSES: none 

IN-ERITED DATA FIELDS; R imeiRect: Rect; Window-relative bounds, excluding 

borders, but including rulers Of 
anyX 
R outexRect: Rect* > -Bounding box in window 

coordinates. 

DATA HELDS: R window: Twmdow; Window in which tnis panel appears. 

R panes: lUst (OF TPane}; The panes of this paneL listed 

row-wise. 
R ourrentvtew. TView; Tne paginated (page preview) or 

unpaginated view on which this 

panel looks. 
R view: TView; The unpaginated view on which this 

panel looks when not in page 

preview mode. This is the view 

installed by your application. 
R peglnatecMew: TPaglnatedvlew; The paginated view, including 

margins, if the panel is currently in 

page preview mode. If not, 

contains NIL. 
R selection: TSelectlon; The current selection. 

R undoSelecticn: TSelectlon; The selection to be restored if the 

last command is undone. 
bands: ARRAY[VHSelectJ OF TLtefc 

The bends in this paneL 
scroQBars: ARRAYt^-Getect] OF TScrolBBar; 

The scrollbars of the paneL 

(scroUBarsRv.hll — the (verLhoriz) 

scroll barsX 
R abilities: /KRAYfVHSelect] OF TAbilltes; 

The abilites of the paneL See the 

CREATE method. 
mininneiDlagonal: Point; The minimum size for mnerRect 

resizeBrancft TBranchArea; Used for resizing the paneL 
R zoomect BOOLEAN; TRUE means that this panel is 

zoomed. 
R zoomFacton RECORD numerator, denoirtnaton PONT END; 

The proportional zooming factor. 
previewMode: TPreviewMode; Preview page breaks and page 

margins. 
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lastCUdc RECORD Describes the last mouse click. 

CASE gotPane BOOLEAN of 

TRUE: (cUckPane: TPanefc The pane of the last click. 
FALSE: (clickPcrint: Point); The ImerRecLtopLeft of 



END; 



contentRect: Rect; 
USldeBaradze: Point; 



taSldeBandSize: Point; 



RW deletedSpUts: TAnay; 



lastcUtfcpene, for use 
when lastCiitfcpene was 
deleted. 
v The part of imerRect excluding 
side bands (such as ruiersX 
The size of the horizontal side 
hand (usually a ruler), which is 
displayed at the top of the panel 
The size of the vertical side band 
(usually a ruler), which is displayed 
on the right side. 

If a TAnay with recordBytes 2, the 
ToolKit stores the splits created by 
the user in the panel whenever the 
panel is shrunk so that it is too 
small to show the splits. Then, 
when the panel is enlarged so that 
it is large enough for the splits, the 
splits are redisplayed. If Nm the 
ToolKit does not store splits, and 
they are lost This is initialized 
to NIL in TPaneuCREATE; you can 
allocate an array and change the 
field if you desire. 



METHODS YOUR APPLICATION WILL CfiLL: 



CREATE (object: TObjBCt; ItsHeap: TMeap; ItsWindow: TWIndow; minHelgm 
mtnwidtrt *tteger ; iuv/ttUlttes, ittHAbUltlet: TAblilttes> 
TPaneU 

ltswmoow is the window containing this panel. 

minHelffit is the minimum height of this peneL 

mJnWWth is the minimum width of this panel 

ItsVttUities indicates the vertical abilities of the panel from this 

set* aBar, ascrolt aSpllt See note 8 for more information. 

ItsH^llittes indicates the horizontal abilities of the panel from the 

same set as ltsv/>ttllttes. 

TPaneLCREATE creates an object of type TPaneL 
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ttgtii^it (selection: TSeiecttorc rtghltanslt: TH^rmansitk 

Selection is a selection object 

ftlfyiTrarelt Is the change in highlighting of the displayed object The 
standard choices are: hNone, hOffToDbn rOffToOa rttmToOa 
hDlmToOff, hOnTaOff, and nonToDlfa 

TPaneLHighlltfit calls setectioohttgftfi^* once for each pad object 
(which includes penes and pages) in the panel object (IJses 
OnAUPadsOoL) 

NewVtew (object- TObJecf ltsExtent: LRect; ItsPrintManegen 

TPrintManager; ItsDfltMargins: LRect; ItsFltPerfecUyOnPages: 
BOOLEAN* TVteW; 

ltsExtent is the size of the view, in view coordinates. 

itsPrintManager is the print manager for the view. 

ItsDfltMargins defines the default margins when the view Is printed 

(can be changed by the user), 

ItsFltPerfecUyOnPages tells whether or not the view should always 

divide into who\e pages for printing. If TRUE, when the view size is 

changed, the ToolKlt automatically increases its size (if necessary), 

Newview creates the view object for the panel. This method or 
NewStatusview is called once and only once for every panel Use 
Newview for printable views. 

NewStatusview (object: TObJect; ltsExtent: LRect): TVIew; 

ltsExtent is the size of the view, in view coordinates. 

NewStatusview creates the view object for the paneL This method 
or Newview is called once and only once for every panel. Use 
NewStatusview for views that cannot be printed. 

OnAUPadsOo (PROCEDURE DoOnThePacfc 

PROCEDURE DoOnThePad is a procedure of no arguments. 

TPaneLOnAUPadsDo applies the given method to every pad object 
(which includes panes and pages) of the panel It focuses the 
grafPort on each pad before applying the method to that pal (The 
global variable thePad is the presently focused pad.) DoOnThePad is 
called once for every pane and page in the panel In "Preview Page 
Margins" mode, DoOnThePad is called once for every page in each 
pane. DoOnThePad cannot be a method. 

OnAllPadsDo should not be called from TViewDraw or 
TSetecttonJ-tt^Ugrt methods, but must be used to call those methods. 
On the other hand, you should use paneLOnAUPadsOo in command 
Mousepress, MouseMove, and MouseRelease methods. 
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METHOOS YOUR /^LIGATION MAY OH±z 
BeglnSeiectlorv 

BegfrSelection sets selectPanel and calls Deselect for selections in 
all panels, in some cases, this method does the same for any current 
diaiocfioxBS. 

BeseiectPanei Qnselectwindow: BOOLEAN* 

lnselectwindow indicates whether' panel is in the selectwmdow. 

TPaneLBeseiectPanei makes panel the seiectPanei of its window, if 
ins&ectWJndow is true, BeSelectPanel also makes that window, 
which mic^t be a dialog box, be the seiectwindow of the active 
window. 

CMWWithPt (pt» Point; chUdUsu TUst; v/« nearestPt: Point* Tftee; 

pt is a point in window-relative coordinates. 
cMldLlst is a list of areas contained within this paneL 
nearestPt is the point in the returned area closest to pt 
The return value is one of the areas from childList 

ChildWlthPt first finds the point in paneUrmeiRect closest to pt It 
then the compares the new point to the outeiRects of all the areas 
inchlkUst When it finds the area that contains the point it finds 
the point in that area's ImerRect that is closest to the point That 
value is returned as nearestPt The area containing nearestPt is the 
return value. 

Divide (vhs: \HSelect; fromEdgeOfPanet INTEGER; units: TUrttsFromEdge; 
whoCartteslzett: TReslzability; mtoSlze: INTEGER; ItsV/tollitles, 
itsHAbillttes: TAMllttes); 

vhs indicates the orientation of the new panel, v divides the panels 

so one is on top of the other; h divides the panels so they are side 

by side. 

fromEdgeOfPanel if positive, is the distance of the split from the top 

left owner; if negative, is the distance from the bottom right comer. 

units indicates whether the fromEdoeOtPanei value is a percentage 

(percentFromEdge) or is in pixels (pbcelsFromEdge). 

whoCanResizeit determines whether the size of the panel varies with 

the size of the window, whether the panel has a resize icon so that 

the user can change its size, and whether the application can change 

the panel's size. 

minSize defines the minimum size of the panel. 

Itsvwiltles indicates the vertical abilities of the panel from this 

set- aBar, aScroil, sSplit See note 8 for more information. 

ItsHMUIttes indicates the horizontal abilities of the panel from the 

same set as Usabilities. 

TPaneLDMde creates a new panel after the first panel in the 
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window has already been created with TPaneLCREATE Divide 
automatically calls TPaneUnsert 

Frame; 

Frame draws the frame of the panel, including the scroll bars. 
HaveVlew (view: TMew); 

view is a view object 

HaveVlew installs the given view in the panel. 

insert (panel: TPanel; vhs: VHSelect; frcmEdgeOfPanei: INTEGER; units: 
TUrdtsFromEdge; wnoCanResizelt: TReslzadlllty)t 

panel is the panel that is inserted 

vhs indicates the orientation of the new panel, v divides the panels 

so one is on top of the other; h divides the panels so they are side 

by side. 

ri on Ed y eOfPanel if positive, is the distance of the split from the top 

left comer; if negative, is the distance from the bottom right comer. 

units indicates whether the fromEdgeOfPanel value Is a percentage 

(percentFromEdge) or is in pixels (pbcelsFromEdge). 

trtuCanReslzelt determines whether the size of the panel varies with 

the size of the window, whether the panel has a resize Icon so that 

the user can change its size, and whether the application can change 

the panel's size. 

TPaneUnsert inserts a previously created panel into the window, 
using the space occupied by SELF (the panel through which Insert is 
calledji You normally do not call Insert directly; it is called for you 
when you use Divide to create a new paneL You can. however, use 
TPaneLCreate to create your own panels, and then call insert 
yourself. 

invalidate; 

Invalidate invalidates the entire panel, so that it is redrawn the next 
time TWindowOJ|f)date is called. 

invalLRect QRecuTMew: URecft 

lRectmvlew is a part of the view. 

TPaneUnvalLRect tells all pad objects (which includes panes and 
pages) in the panel object to perform thePad&ivaiLRect on 
themselves* (Uses OnAUPadsDa) 
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OkToOrawm QRectlhVlew: LRecQt BOOLE** 

fRectmview 1$ a view-relative rectangle. 

A return value of TRUE Indicates that the application can safely call 
Draw methods or QuickDraw and UDraw routines, (firectly (rather 
than calling paneUnvalRect to cause drawing in the next Update) 
within the rectangle lRectirMew. An application or Duilding block 
should always call OkToOrawm before attempting to draw or erase 
directly when giving feedback (exbept for XOR feedback) in response 
to a user action or command. If permission is denied, the application 
should call TPaneUrwalLRect (which may display more slowly), rather 
than a Draw method. TPaneLOkToDrawm checks to see if 
IRectlnMew includes a page break, which will only occur when the 
document is in "Preview Page Breaks" mode. If it does, it is not safe 
to Draw, and the return value is FALSE. Otherwise, 
TPaneLOkToDrawm calls view.OkToDrawm. you can reimplement 
view.OkToDrawln so that it actually checks to see if it is safe to 
draw in lRectinView. TVlew.OkToDrawIn always returns FALSE. 

PaneShowlng (anLRect: LRectfc TPane; 

anLRect is rectangle in the view looked on by this peneL 
The return value is one of the pane's penes. 

PaneShowing returns the first pane in paneLpanes that shows some 
part of anLRect 

PaneToScroU tyfiR anLRect: LRect; rt-ttnToSee, VMinToSee: INTEGER): 
TPane; 

anLRect is rectangle in the view looked on by this panel. 

hMtaToSee is the minumim horizontal portion of anLRect that you 

want to see. 

vMinToSee is the minumim vertical portion of anLRect that you want 

to see. 

The return value is one of the panel's pares. 

PaneToScroU is called by TPaneLRevealLRect to obtain the pane that 
should be scrolled to reveal the Indicated minimum portions of 
anLRect Your application might call this method directly. 

Preview (jnewMode: TPrevtewMoo^t 

newMode is the new preview mode from the Page Layout menu. 

Preview displays the pageVlew version of the view looked on by this 
peneL 

Printview (prfntPref: TPrReserve); 

printPref are the printer preferences. 

Printview prints the vtew looked on by this peneL 
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Refresh (rActions: TActtons; h&mansit: THLgmansitfc 

rActtons is from the set (rErase, rFrame, iBackgrouna roraw). 
tfghTranstt is the change in highlighting of the displayed object The 
standard choices are: hNone, hOffToDim, hOffToOn, hDtmToOn 
hDimToOf f , hOnToOf f, and hOnToDim. 

Refresh refreshes the panel's display. Update sets up the grafPort 
for the invalidated portion of the panel's view, and then calls 
Refresh. If there is no invalid pdrtion. Refresh is not called 

Remove; 

TPaneLRemove takes the SELF panel out of the window. The panel 
that was divided to create space for this panel is e^qsanded to fill the 
space. TPaneLRemove does not free the peneL 

Replace (panel: TPanelJt 

panel is the panel that is to he inserted 

TPaneLReplace replaces the SELF panel with the given panel The 
panel that was removed is not freed. The new panel is resized to ftll 
the space occupied by the old panel. 

Resi2elnside (newImeiRect: Rect]t 

newlmerRect is the panel bounds excluding borders. 

Reslzemslcte changes the size of paneUnnerRect it performs 
higher-level operations on the panel such as resizing areas contained 
within this panel including bands, and then calls SELF.SeUmeiRecL 

ReslzeCXJtslde (nevOJteiRect: Rectfc 

newOuterRect is the bounding box. 

ReslzeOutslde changes the size of panels and Invalidates the changed 
areas. It performs hi^er-level operations on the panel such as 
resizing areas contained within this panel and then calls 
SELFjSetOuteiRecL ResizeOutside calls Reslzelnside, 

Rescron; 

Rescroll is called when the view changes drastically. It fixes the 
elevators so that they are positioned correctly. The entire panel is 
invalidated. 

RevealLRect (vW anLRect: LRect; rMnTaSee, vMnToSae: WTEQER); 

anLRect an rectangle in the view. 
hMlnToSee a horizontal distance, in view units. 
vMtaToSee a vertical distance, in view units. 

RevealLRect scrolls the panel so that some part of anLRect shows in 
a pena hMOToSee and vMnToSee define the minimum part of 



11-93 



.Lisa. ToolKit Reference Manual Part II Class Reference Sheets 

anLRect that is displayed after the scroll This method calls 
TPaneLPaneToScroll to obtain the pane that should be scrolled to 
reveal anLRect 

SetZoomFactor (zoomNumeratoar, zoomDenomftnaton polntfe 

zoomMmerator is a point containing the vertical (zoomNumerator.v) 
and horizontaKzoomNLfneratoriTi) numerators of the zoom factor. 
zoom P enom i na to r is a point containing the vertical 
(zoomDenomlnator.v) and horizont^ztxviDenomlnetorJh) denominators 
of the zoom factor. 

SetZoomFactor sets a zoom factor that translates sizes between the 
view and the panel The factor is a set of two fractions, one for the 
horizontal zoom factor and one for the vertical zoom factor. Each 
fraction is broken up into two numbers, a numerator and a 
denominator. The set of numerators is stored in the point 
zoomNunerator and the set of denominators in the point 
zoomOenominetor. (Warning: this feature has not been debugged.) 

Showaoeeana (vhs: VHSelect; toponeft: BOOLE/v* size: */TEGER; 

VtewLCdb LONGNT); 

vhs indicates the orientation of the side band: vertical or horizontal 

A vertical side band appears at the top or bottom of the panel; a 

horizontal sideband appears on the left or right side. 

topOiLeft indicates whether the side band is on the top or the left 

side of the panel For example, if TRUE, and vhs is v, the side band 

appears on the top of the panel 

size is the size of the side band in vhs direction. 

viewLCd is a view-coordinate number that indicates the part of the 

view that shows in the sideband. This is usually some negative 

number. The number does not change the a ppea r ance of the side 

band except that if the number is positive, it is part of the view, can 

be scrolled, and can be printed. 

ShowSideBand displays a side band. The side band is always 
displayed with a 20 pixel gap between it and the panel 

SkteBandRect (vht MHSelect; topOrLeft- BOOUE/W VAR bantftoct: Recft 

vhs indicates the orientation of the side band: vertical or horizontal. 

A vertical side band appears at the top or bottom of the panel- a 

horizontal sideband appears on the left or ritfft side. 

topOiLeft Indicates whether the side band is on the top or the left 

side of the panel For ex ample , if TRUE, and vhs is v, the side band 

appears on the top of the penel 

banGRect is the InneiRect of the side band. 

SdeBandRect returns the InneiRect of the side band, given 
SELFjoontentRect You probably will never call this method. 
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FAILURE CONDITIONS: None 

NOTES: 

1. TPanel is never subclassed. 

2. A panel is the part of a window that looks onto a particular view. 

3. There may be several panels In a single window. Each one normally 
displays the contents of a different view pbject 

4* peneLCREATE is normally called once for each window. To create more 
panels, call paneLDMde once for each additional panel Divide calls 
paneLCreate and then paneLInsert. 

5. If you want to add a panel as quickly as possible, you can call CREATE 
when you initialize your window, and store the panel away. When you 
want the panel to appear on the display, call peneureert 

6. The pane objects that control the panes within the panel are what actually 
display the visible portion of the view object "me panel object controls 
the scrolling of those panes. 

7. Every panel initially gets one pane. The user may create additional panes 
if one of the TAbilitles given is aSplit. It is not necessary for your 
application to mention pane objects. 

8. The T/Yrtlittes are: 

aBar, which gives a gray bar with no scrolling ability. 

ascroii, which gives a scroll bar (a gray bar with flippers, 
scrollers, and elevators), and allows autoscrolL 

aSplit, which gives a pane splitter. 

These abilities are independent; give a list of the ones that you want. 
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CLASS: TPasteOommand 

SUPERCLASS: TOommand 

DEFINED SUBCLASSES: none 

INHERITED DAT A FIELDS: R cnxNumben TCmdNunter; 



R vlewiTVteW; 



R undoable: BOOLEAN; 



R doing: BOOLEAN; 



revelation: TRevelstion; 



Tne command number of 
the menu Item that 
describes the command. 
Tne view to vrfilch the 
command applies, or NIL 
If the data Is stored in 
the window. 
TRUE means that this 
command can be 
reversed. 

This value is TRUE if the 
last call to Perform was 
In doPhase or redopnase. 

Determines how much of 
the selection should be 
automatically scrolled 
into a pane when the 
command is performed. 
Can be none (no 
scrolling), some (scroll to 
show some part of the 
selection), or all (scroll 
to display the entire 
selection, if possible). 

W unHUlteBefoie: /«RAY tTOmdPhase] OF BOOLEAN; 

TRUE tells the ToolKit 
to remove the 
hiojhllojhting from ail 
selections before Perform 
is called. 

W hlliteAften ARRAY pUndPhase] OF BOOLEAN; 

TRUE tells the ToolKit 
to add highlighting to all 
selections after Perform 
is called. 



DATA FIELDS 



none 
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METHOD YOUR /VPUCATK3N MUST OVERRIDE: 

CREATE(objBct: TObJect; ItHeep: THeep; ItsCmdNumben TUndNumber; 
itsVlew: TVtew> IPasteCommend; 

itscmdhtmber is the command number of a menu command 
ltsview the view to which the command applies, or nil If the data is 
stored in the window. 

TPasteCommarclCREATE creates>an object of type TPastecommand. 

DoPaste (ciipSelectiort TSelectton; pic: picHandle; cmdPhase: TDmdPhaset 
DEFAULT; 

clipSelection is, when cmdPhase-doPhase or redoPhase, the selection 

object that indicates what objects are to be inserted. When 

cmdPhase-undoPhase cllpSelectlon is NIL. 

pic is the handle of a QuickDraw-picture representation of the data 

in the clipboard or NIL. 

cmdPhase is either doPhase, undoPhase, or redoPhase. 

DoPaste executes the paste. Either clipSelection or pic is used to 
indicate what is to be pasted into the document If cUpSeiection is 
not ML* it indicates a set of ToolKit objects in the clipboard. If 
clipSelection is NIL, pic references a QuickDraw picture that is to be 
pasted into the document The first time DoPaste is called, the 
cmdPhase is doPhasa After that undoPhase and redoPhase alternate. 
Do not call this routine directly; it is called by Perform. 

When cmdPhate Is doPhase or redoPhase, DoPaste must done the 
contents of the clipboard, and put the copies into the document 
When cmdPhase is undoPhase, DoPaste must delete the added 
information from the document On doPhase and redoPhase, the 
clipSelection mi<yit be NB. if there 1$ no view to paste or if the 
selection is a generic TSelectton. in that case, information for the 
paste must be obtained from pic. 

METHOD YOUR APPLICATION WU. C^LL: 

CREATE (object: TObJect; itHeap: THeep; ItsCmdNumben TCmdNumber; 
ItsVlew: TView> TPastecommand; 

See above. 

METHODS YOUR /APPLICATION MTCHT OVERRIDE: 

Commit; 

You can override Commit if you want to implement the paste so that 
it uses a filter when Perftxm is called, in that case. Commit 
changes the document, while DoPaste simply copies the contents of 
the clipboard into someplace Commit and EachVirtueflPart can reach. 
TPasteOommanC L Oommtt does nothing. 
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EachVlrtuaiPart (PROCEDURE DoToObJect (fUteredOb* TObJectJt 

PROCEDURE DoToObJect (fllteredObi TObJect) Is a procedure that 
filters filteredObj before fUteredObJ is displayed. DoToObJect cannot 
De a method. 

EachVirtualPart is used in implementing a filter. A virtual partis a 
selectable part of the set of objects. Every virtual part must be an 
object DoToObJect acts on the object it is given. When you 
Perform the paste command with fcmdPhase equal to doPhase copy 
the contents of the clipboard into a temporary list When drawing 
the view, use EachVlitualPart to draw the original document as well 
as your copy of the just pasted list When you Commit the 
pasteOommand copy your copy of the clipboard contents into your 
application's set of objects. 

INTERNAL t*ETHOO: 

Ferftxm (cmdPhase: TOncPhase); 

cmdPhase is either doPhase, undoPhase, or redoPhjase. 

TPasteCommandPerform calls past e oommanC L DoPaste to execute the 
paste command. The first time Perform is used, the cmdPhase should 
be doPhase. After that undoPhase and redoPhase alternate. 

FAILURE CONDITIONS: none 

NOTES: 

1. See TComrnand for general information on comman d implementation. 

2. TPasteCommand is used to paste the contents of the clipboard into the 
document The clipboard contents are inserted at the place indicated by 
the selection 

3. You must override this class to use it At a minimum, you will have to 
implement DoPasta Note that building blocks often implement this for 
you 

4. The clipboard can be loaded by a cut or copy operation by your own 
application or by another ToolKlt application. If the clipboard is loaded 
by another application, the ToolKlt converts the data to a better form for 
your application before pasting the data into your document (The 
conversion is done by TOACfipyCommendPerfonn.) Every object that was 
of a class your application does not have is converted to an object of an 
ancestor class that exists In your application This trans for m a tion process 
can lose information 

5. Before you copy the data, you can use Indass to test the class of 
dlpSetectJon As you copy the data, it is a good idea to examine each 
component that migpt have been an object of another class in another 
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application. You can sometimes use mciass to help transform objects 
from the- clipboard into objects of classes that your application is prepared 
to process, "mis is demonstrated in the examples in the ToolKit 
Segments. 

6. See the ToolKit Segments for examples of using TPasteCommand and 
further explanations. 
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class: TPimtManager 

SUPERCLASS: TObjBDt 

DEFINED SUBCLASS: TStdPrintManager (defined in the Dialog Building Block) 

INHERITED DATA FlELDSt none 



DATA FIELDS: view: TVIew; 

pageView: TVIew; 



The view whose printing is managed 
v by this prlntManager. 
'The view that draws the headings 
in the margins of the page. The 
size of this view is the size of one 
page, 
breaks: ARRAY[*Setect] OF TAnay {of LONGHNT}; 

The vertical and horizontal 
pagebreaks that divide the view 
into pieces that fit onto individual 
pages, breaksfv] holds information 
for page breaks that, when drawn 
on the screen, are represented by 
vertical lines; breaksfh] holds 
information for page breaks that 
when drawn on the screen, are 
represented by horizontal lines. 
The absolute value of each array 
element gives the location of the 
break in the view; the sign tells 
vrtiether the break is an automatic 
one (nomegative) or a manual 
(user-set) one (negative). 
The page margins to use when 
fitting view pieces onto pages: top 
and left are positive and bottom 
and right are negative. These 
numbers are in view coordinates, 
which is why the values are LRects 
even though the actual numbers 
involved are smalL 
The headings to be printed on the 
nao fts , 

FALSE by default; the 
stoPrt ntManager sets this TRUE, as 
headings and margins can be edited 
with the page. 

ML by default; the stdPrintManager 
places a reference to a dialog box 
It creates here. 



PBQp^RrnlnSi LRect; 



headings: TLlst Jof THeadlngl; 
canEdUPages: BOOLEAN; 

layoutDialop^ox: TDiatogpox; 
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ftameBody: BOOLEAN; 



pepeiLRect: LRect; 



prtntableLRect: LRect; 



oontentLRect: LRect; 



printeiMetrics: TPiinteiMetiics; 



pageRlseDlrectlon: vhSelect; 



METHODS YOUR APPLICATION MAY OVERRIDE: 



FALSE by default; you can set it to 
TRUE, in which case the page body 
is separated from the page margins 
on the printed page by a box 
Mostly for debugging purposes. 
The physical bounds of a single 
page on the current printer, in view 
coordinates. 

The printable area of a single page 
on the current printer, in view 
coordinates. 

The area on a page into which the 
body (that is, sections of the main 
view) will be placed, obtained by 
taking the pepeiLRect and allowing 
roo m for the margins specified in 
the pageMarginSw 
The data characterizing the 
physical properties of the printer 
currently formatted for; this is a 
RECORD whose fields are: 
peperRect, prlntableRect (the 
counterparts of pepeiLRect and 
printableLRecL but In grafPort 
coordinates), and res (the 
resolutions of the device, packaged 
Into a Paint). 

Whether page numbers should be 
assigned left-to-rigfit (hj) or 
top-to-bottom (vX 



CREATE (object: TObJect; heap: THeap> TPrintManager; 

TPrintManeger.CREATE creates an object of type TPrintManager. 

DrawPage; 

Draw the page with the page-number Indicated by 
theMaiglnPadLpagBNumber. 

EnteiPageEdltlng; 

Enter into whatever method the printManager has of allowing the 
user to edit page headings and margins. 
7PrtntManager£nCeiPageEolUng does nothing. 
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QetPageUmtts (pageNumben LONGDsfT; v/W vtewLRect URectJt 

pageNumber Is the number of one of mis application's pages. 
vlewLRect Is the part of the application's view that makes up the 
body of the given page. 

Given the page number, returns the bounds of the part of the view 
that makes up the body of that page. Your application can call this 
method. 

NevPaglnatedViev (object: TObjecQc TPaglnatedVlew; 

The return value Is a peglnetedVlew. 

TPrintManagar.NewPaginatecMew creates a new paglnatecMew. By 
default, the ToolKit's standard Page-preview mode Is Invoked. 

NewPageMew (object: TObjecQt TVlew; 

The return value is a pageVlew. 

TPrintManager-NewPageVlew creates a new pageVlew. By default, an 
object of the ToolKit's standard TPageVlew class is launched 

PageWith (V/YR lPtlrMewi LPoint; VAR strip: PoJnQLONGINT; 

IPUriVlew is a point in the application's view. 

strip is the vertical and horizontal strip of pages that contain 

iPtwview. 

The return value is the number of the page that contains iPUhVtew. 

Given a point in the view, PageWlth returns the page number into 
which that point fails, as well as returning the vertical and horizontal 
strip of pages containing the IPtwview. Your application can call 
this method. 

Print; 

TPrtntManagarPrint orders the actual printing. You might override 
Print in order to do something special before or after printing, in 
that case, call SUPERSELFPrint for the actual printing. You can 
override Print entirely and handle printing yourself, but you must 
then have direct access to the underlying Lisa Printing software. 

ReactToPrinterChange; 

TPrimMaragerjReactToPrinteiChangB reacts to a change in printer 
specification. TPiWManaMJReactToPrlnterChange gets fresh printer 
metrics, recomputes the pnntabteLRect papeiLRecl and 
contentLPect resizes the view if necessary, recomputes the bounds 
of the pageVtew, and calls RedoBreaks. This method is called by 
TVlewJfeactToPrinteiCtange. Your application can call this method. 
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RedoBreaks; 

TPrintManagerPedoBreaks recomputes page-breaks. Your application 
can call this method. 

setDfltHeaamgs; 

SetDfltHeadlngs in intended to set the default headings. It is called 
by TPrintManager Jnlt so that the printManager can create desired 
default headings and install therein its list of headings. 
TPrintManager^etDfltHeacflngs does nothing. 

SklpPage (pageNumtoen LONGING 

TPrintManager-SkipPage does nothing. You can override this routine 
to do whatever you want to do when that the indicated page-number, 
at printing time, is not going to be printed but larger page-numbers 
will be. This allows an application to cycle through its data 
structures to the start of the next page, if it needs to. 

METHOD YOUR /VPUCATION MAY CAUU 

ChangeMargins (newMarglns: LRectk 

Install a new set of margins into the printManager. 
NOTES: 

1. A printManager must be associated with every printable view. 

2. You associate a printManager with a view t>y handing a refe r ence to a 
printManager to the method that creates the view. The 
printManager-reference is then placed in the vtew^arintManager field. If 
the view is not printable, hand NIL to the method that creates your view 
(usually paneLNewVtewX 

3. You can use an instance of TPrintManager for your printManager. In that 
case, simply call TPrintManagerjCREAT^, and install the resulting object 
in vlew.printManager. The view will be printable, but you will not be able 
to specify headings or margins. 

4> Alternately, you can use the Dialog Building Block class TStdPrintManager. 
Call TStdPrifkManag e r . CREAT5, and Install the resulting object In 
vtew.printManager. The view will be printable, and you will be able to 
Interactively create and edit headings and margins through the use of the 
Headings and Margins dialog. In this case, you must USE the Dialog 
Building Block. 

5. As a third alternative, you can create your own subclass of TPrintManager 
or TStdPrintMangager, and give an instance of that to the method that 
creates your view. 
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6. Once a printManger is installed in your view, the same drawing methods 
that draw in your application's window on the screen can draw on the 
printed page. The ToolKit takes care of converting the output so that it 
appears correctly on the printer. 
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**«clas& TProcess 

SUPERCLASS: TObJect 

DEFINED SUBCLASSES none 

INHERITED DATA FIELDS: none 

DATA FIELDS: None. However, the global variables are Important to the 

process. See Chapter 6. 

METHODS YOUR APPUCATION MUST OVERRIDE: 

CREATE (object TObJect; heap: THeap) Tprocess; 

7Process.CREATE creates a process object 

NewDocManager (volumePreflx TFllePath; openAsTooL- BOOLEAN): 
TDocManager; 

volumePreflx, a name of the form -VOLUMEHdocumentnumber), Is set 

by the ToolKit Your application simply passes the value along. All 

files that comprise the document begin with the string contained in 

volumePreflx 

openAsTool defines whether or not the Tool Icon was opened by the 

user. The calculator and clock are examples of applications where 

this is true, 

NewDocManager creates a docManager object for the process. The 

method you write should call the CREATE method for your 
descendant of TDocManager. If you do not want your application to 
create a docManager, return NIL You can do that when the user 
tries to open the tool and the tool cannot be opened, or when the 
application cannot handle another document See the ToolKit 
Segments for detailed descriptions of how your application is 
initialized. 

METHODS YOUR APPUCATION WEJL CALL: 

Comm en ce (phraseversion: INTEGER); 

phraseversion is a version number used to check that the proper 
phrase file is on the disk. No version check is done if 
phraseversiomo. A mismatched phraseversion is only a warning. The 
ToolKit does nothing. 

TProcess-Commence Initializes a process. 
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Complete (aUIsWelk BOOLEAN); 

alllsWell Indicates whether or not the process completed successfully. 
The application program normally passes TRUE The ToolKit passes 
FALSE when there has been an error. 

TProcess.Complete signals that the process has finished. It 
terminates the OS process, and never returns to its caller. 

Run; 

TProcessRun starts the main event loop running. 

METHODS YOUR APPLICATION MIGHT OVERRIDE: 

Commence (phraseversion: INTEGER); 

See above. You might override this method in order to initialize 
some of your own global variables. In all cases, you should call 
TProcessXto m mence before initializing your own variables. 

Complete (alUsWelk BOOLEAN); 

See above. You might override this method in order to clean-up 
after your process. Call TProcess-Complete after finishing your own 
cleanup. 

OTHER METHODS: 

ChangeCursor (cursorNumber. TCursorNurnber); 

oursorNumber is the reference number for an application or ToolKit 
defined cursor. 

ChangeCursor changes the cursor to the given cursor shape. 
Applications may call this routine. ChangeCursor calls 
DoCursorChange. 

DoCursorChange (cursorNurnber: TCursorNurnber); 

cxorsorNumber is the reference number for an application or ToolKit 
defined cursor. 

TProcessXtoCursorCfrwnge handles standard cursor numbers. 
Applications can reimplement DoCursorChange in order to test 
cursorNurnber for one of the application's special cursor shapes. If 
trie cursorNurnber is defined as one of your application's special 
cursors, DoCursorChange should call QuickDraw's setCursor routine. 
If the cursorNurnber is not one of your special cursors, your 
DoCursorChange should call SUF^RSELPIXCursorChange. 
Application cursor numbers start at 100. 
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TrackCursor; 

"TrackCursor tracks the cursor while the process is in its idle loop. It 
eventually calls view.CursorAt where you get a chance to set up your 
own cursor. 

ArgAlert (whichArg: TAlertArg; argText: S255)c 

whichArg is a number from 1 to 5, corresponding to the *l to "5 ' 
placeholders in the phrase file. £ Q, in the phrase file, is replaced by 
the tool name given when you run the Install program.) 
argText is the text you want to replace the given placeholder. 

ArgAlert replaces the whichArg placeholder with argText The text 
is included the next time an alert with that placeholder is displayed. 

Ask (phraseNumber: IN7EGER> INTEGER; 

phraseNumber Is the phrase file reference number for an ask alert 
The return value Is the number of the button the user pressed. 

Ask displays an ask alert which is an alert that presents the user 
with choices. 

Beginwait (phraseNumber: INTEGER); 

phraseNumber is the phrase file reference number for a dialog. 

Beginwait displays a wait alert 
Caution (phraseNumber. INTEGER* BOOLEAN; 

phraseNumber is the phrase file reference number for a dialog. 

Caution displays a caution alert using the text referred to ty 
phraseNumber. 

CountAlert (whichCtr: TAlertCounter; counter: INTEGER); 

whichCtr is 7 to 9. 

counter is the number you want displayed in whichCtr. 

CountAlert changes the number displayed in a wait alert 

DrawAlert (phraseNumben INTEGER; marginLRect LRectfc 

phraseNumber Is the identification number of the alert in the phrase 

file. 

marginLRect is the size of the text area of an alert box. Only the 

top, left and right values matter. The ToolKit extends the bottom of 

the alert to allow room for the text associated with phraseNumber. 

DrawAlert draws an alert box. 

EndWalf 

EndWait ends a wait alert 
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QetAlert (phraseNumber. INTEGER; VAR theText S255); 

phiaseNumber is the phrase file reference number for a dialog. 
theText is the text of the alert referred to by phraseNumber. 

GetAlert obtains the text string of a given alert from the phrase file. 
Note (phraseNumber: INTEGER); 

phraseNumber is the phrase file reference number for a dialog. 

Note displays a note alert 
RememberCornmand (cmdNumben TOmdNumber); 

cmdNumber is the number of an application or ToolKit command. 

RememberCommand remembers the last command given for use in an 
alert The command is used to replace the "C and "K placeholders 
in the phraseflle. "K displays the command exactly as it appears in 
the menu. "C converts the command to all lower case. This method 
also resets the counter for staged alerts. A staged alert is one 
where the alert response changes if the user repeats the action. For 
example, when you type on the Lisa when that is not allowed, the 
Lisa beeps on the first two keystrokes. An alert is displayed after 
the third keystroke, to point the error out RernerrtjerCornmand 
resets that counter, on the assumption that, since the user executed a 
command, the errors were not continuous. 

Phrase (erron INTEGERS INTEGER; 

error is an error number. 

Phrase should return a phrase number for a given error. If the return 
value is phtinknown, refer to SuLib(OSERRS.ERR) in the Internals 
document to get the text of the error message. 

Stop (phraseNumber. INTEGER); 

phraseNumber is the phrase file reference number for a dialog. 

TProcess^Stop usually displays a stop altert using the text referred to 
by phraseNumber. If there is no active document, it halts the 
process and initiates a dialog with the user. 

AbortRequest: BOOLEAN; 

If aborts are allowed, the return value indicates whether or not the 
apple/period cxKnmand was typed. TRUE indicates that command was 
typed. 

rtxnrtRequest indicates whether the user has requested a command 
abort You can call this periodically during a long command to tell 
if the user is trying to abort the command. 
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/toortXf&rSequenUal (whlchWay: xReadWrlte; pFirst: Ptr; numBytes, 
chunkSize: LONGINT; ffc TFUeScarmer); 

whichWay defines whether the operation is a read or write. 

pFirst is a pointer to the first byte to transfer. 

numBytes defines how many bytes are transferred 

chunkSize is the number of bytes to transfor before testing for an 

abort command. 

fs is an active file scanner. 

AbortXferSequentlal acts the same as XferSequential, except that it 
checks AbortRequest after each chunkSize bytes of data are 
transferred. 

OtoeyEvents (FUNCTION StopCondiUon: BOOLEAN); 

StopConffition is a ToolKit function that returns TRUE if some 
condition requires suspension of the process. 

ObeyEvents is the main event loop for the process. It normally 
returns only if amoving is TRUE, which indicates that the application 
is terminated or StopCondition returns TRUE. StopCondition is 
checked only when no events are available. 

ObeyFilerEvent; 

ObeyFilerEvent is called by the ToolKit when a filer event is 
received for a document owned by this process. 
TProcess.ObeyFilerEvent calls an appropriate routine, usually a 
method of TDocManager, to handle the particular event 

ObeyTheEvent; 

ObeyTreEvent is called by the ToolKit when an event is received for 
the process. TProcessXto ey TheEvent then calls an appropriate event 
handling routine, which may be a ToolKit or an application routine. 

HandlePrtvateEvent (typeOfEvent INTEGER; fromProcess: LONGINT; whert 
LONGINT; OtherOata: LONGflNT); DEFAULT; 

typeOfEvent is an event type number. This is generally 100, but 

other numbers may be defined in building blocks. 

fromProcess Is the OS process ID for the process that sent the event 

You can pass in the process ID by using the OS procedure 

lnfo_Process. 

vrfen is the clock time when the message was sent 

otherData is some data sent t>y the process. 

HantflePrivateEvent is called by the ToolKit when an event is 
received from another process. If you want your application to 
process such events, you must Implement this method. 
TProcessJHancQePrivateEvent does nothing. 
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SendEvent (typeOfEvent* INTEGER; targetProcess: LONGINT; otherData: 

LONGINT); 

typeOfEvent is an event type number. The possible numbers are 100 

and above. 

targetProcess is the OS process ID for the process that is to receive 

the event You can pass in the process ID by using the OS 

procedure Inf o_Process. 

otherData is any information you v want 

SendEvent sends a message (an event) to another process. 

BindOtmrentDocument; 

BindCurrentDocument puts the data segments for the document 
currently being used by this process into memory. You should not 
need to call this method; the ToolKlt binds your data segments for 
you 

FAILURE CONDITIONS: none 
NOTES: 

1. TProcess is the default process class. You always create a subclass so 
that your application's type of process object is created In the subclass 
you must define a NewWindow method that creates your kind of window 
object. 

2. A ToolKit process is not the same as an OS process. An OS process is a 
particular instance of a program that may be executing. A ToolKit 
process, the only kind discussed in this manual, is the control object in a 
ToolKit program. There is, at most, one ToolKit process in an OS process. 

3. A program must create an instance of a descendant of TProoess in order 
to run under the ToolKlt 

4. No program may use more than one instance of TProcess or a descendant 
of TProcess. (Note, however, that a second OS process can be started by 
a ToolKit process.) 

5. Normally, a main program creates an Instance of its TProcess descendant, 
and then initializes, commences, and runs the process. When the 
processJ^un method call is. given, the process waits for events from the 
program user. The applications implementation unit and the ToolKit 
contain methods that respond to events, and carry out the actual work of 
the application. If the process completes successfully, processJ^un 
completes, and the main program uses process.Cfcmplete(TRUE) to signal 
successful completion, if the process falls with an error, 
process-CompleteF/^SE) is called by the ToolKit Normally, a ToolKlt 
process does not complete until the office system is shut down. 
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6. TProcess is normally the only class mentioned in a main program. It is 
not normally mentioned in any unit, except for in its own definition. 

7. For more information on alerts, and how to set them up, see the Phrase 
File document 

EX/Y*PLE 

The following is a sample main program. After that is the section from the 
application's interface unit showing the definition for the class TSamProcess. 
The third program fragment is a section of the application's implementation 
unit showing the implementation of TSamProcess. Note that, other than 
CREATE and NewOocManager, all methods of TSamProcess are inherited from 
TProcess without being overridden. 

PROGfWI Sample; [This is an example of a main program} 

USES 

fOTE: Do not omit any unit that defines classes. These units are 

always given in this order.} 

{$UUObJect fUObject, 

{$U QuickDraw } QuickDraw, 

{SU UDraw j UDraw, 

{3JUABC }UABC, 

|SU USample } USample; {This is the application's unit 

Applications can have several units 

here.} 

CONST 

phraseVerslon - l; 
BEGIN 

process ?- TSamProcess-CREATE; (NOTE: You 
must define your own subclass of 
TProcess.} 
pnxjess.Oomfrence(phraseversion); 
procession; 
process.Complete(TRUE); 

END. 

The following subclass definition appears in unit Usample: 

TSamProoess - SUBCLASS OF TProcess 

FUNCTION TSamProcess^REATE: TSamProcess; 

FUNCTION TSamProoessJvlewDocManage i (vbIumePreflx: TFilePatrfc 

T D ocManager; 
END; 
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The following method definitions appears in file Usample2, the implementation part of 
Usampie. 

FUNCTION fTSarrProcessjCREATE; 
BEGIN 

SELF :- TSamProc3ess(TPiocess.CREATE(ob)ect v heap)); 
END; 

FUNCTION {TSamProcessJ NewOocMSnager (voiumePrefix: TFilePath> 

TDocManager; 
BEGIN 

NewOocManager ?- TSamDocManager.CREA7E (mainrieap, 

voiumePreflx); 
END; 
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CLASS: TScanner 

SUPERCLASS: 
DEFINED SUBCLASSES: 



TObJect 

TArrayScamer 

TFlleScamerP (subclass of TStringScanner) 

TUstScanner 

TStringScamer 



INHERITED DATA FIELDS: none 

DATA FIELDS: R collection: TCollectlon; 
R position: LONGINT; 



R increment- INTEGER; 



scanDone: BOOLEAN; 



R atEnct BOOLEAN; 



The collection being scanned. 
The current position of the scanner. 
The scanner position is always 
between, before/ or after members: 
0-before first, size*l-after last 
The change in position for every 
scan: 1 if scanning forward, -1 if 
scanning backward. 
When this is TRUE, the next Scan 
call returns F^_SE, signalling the 
end of the scan. The vw parameter 
of the Scan method, which normally 
contains the next object in the 
collection is unchanged after the 
Scan calL 

TRUE if the end of the collection is 
eminent, so that the next Scan call 
will return FfiLSE. 



METHODS: 



CREATE (object TObJect; ItsCollectiort TCollectlon; ltsInltialPositiort 
LONGONT; itsScanDirectiort TScanDirection): TScanner; 

itsCoUection is a collection object 

itsInitialPosition is the initial ordinal position in the collection. 

itsScanDirection is scanForward or scanBackward. 

TScanner.CREATE creates an object of type TScanner, which is 
used to access ItsCoUection. itsCoUection must exist before a 
scanner can be created for if however, you can use a 
TCollection-CREATE call in your TScamer.CREATE call which 
will create the necessary collection object You never call this 
method directly. 
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Advance (PROCEDURE DoToCuirect(anotherMent>er. BOOLEAN^ 
BOOLEAN 

DoToCunent is a procedure that takes a member of the collection 
an an argument. 

The return value tells whether or not the end of the collection 
has been reached. 

Advance begins at the beginning pf the collection and, each time 
it is called, returns the next member. The returned member is 
referred to as the a/tt®^ member. The value of Advance is 
TOUE until Advance is called after the last member in the 
collection is reached, or until scanneriDone has been called. 
When Done is called or the scanner reaches the end of the 
collection, the scanner is freed, you never call this method 
directly. 

Allocate (Slack: LONGINT); DEFAULT; 

slack is the amount of space added to the collection, in bytes. 

Allocate adds empty space to the collection, so that subsequence 
write operations work more quickly. It acts similarly to 
SELFj»ilectioaStartEdlt(slack)L 

Append (member: "TMember"); CONCEPTUAL; 

member is a new member of the collection. 

Append adds member to the collection Immediately after the 
current position, position is adjusted by adding 1, so that the 
next Scan returns the member after the new member. 

Close; DEFAULT; 

Close is intended for use with disk-based files. It closes the 
collection scanned by this scanner object The collection object 
and the scanner object are not deallocated; you can use the 
scarmerX3pen method to reopen the collection. 

Compact; DEFAULT; 

Compact rewrites the collection so that it uses the minimum 
amount of space necessary. 

Delete; CONCEPTUAL; 

Delete deletes the member at the current position, position is 
adjusted by adding the scanner increment 
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DeleteRest; CX3NCEPTUAL; 

DeleteRest deletes all members after the current position, if 
scamerJncrement Is *l, or after the current position. If 
scamerJncrement is -1. position Is unchanged. The next call to 
scamer.Scan returns F^LSE. 

Done; DEFAULT; 

Done signals that you are finished using this scanner. The next 
call to scamer^can returns FfiLSE, as if the end of the collection 
had been reached Unlike when the end of the collection is 
reached, however, the returned collection member in Scan remains 
unchanged. 

Obtain: TMember"; CXDNCEPTUAU 

The return value is a member of the collection. 

Obtain returns the current character. 

Open; DEFAULT; 

Open is intended mainly for use with disk-based files. It opens a 
collection previously closed by scamer.Closa The collection must 
have been closed by this scanner. 

Replace (member: "TMemberTt CONCEPTUAL; 

member Is a member that replaces the current collection member. 

Replace removes the current character from the collection and 
replaces it with the given character. The new character is now 
the current character. 

Reverse; DEFAULT; 

Reverse changes the direction of the scan. 

scan (VAR member: "TMemberT: BOOLEAN; CONCEPTUAL; 

member is the next member of the collection. 

The return value is F^_SE if the end of the collection has been 

reached or scanneriDone has been called. 

Scan begins at the beginning of the collection and, each time it is 
called, returns the next member. The returned member is referred 
to as the current member. The value of Scan is TRUE until Scan 
Is called after the last member in the collection is reached, or 
until scannerDone has been called If the end of the collection 
was reached, and Done was not called, the value of member Is 
NIL. If Done was called, member keeps the last value it had. 
When method Done is called or when the scanner reaches the end 
of the collection, the scanner is freed. 
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Seek (jnevPQSitiort LONGING DEFAULT; 

newPositlon is the location to which you wish the scanner to 
move. newPositlon - is the beginning of the collection. 

Seek moves the current scan position to newPositlon it transfers 
no data. 

Skip (deltaPos: LONGINTfc DEFAULT; 

deltaPos is the number of bytes you wish the scan position to 
move within the collection A positive value moves the position 
toward the end of the collection; a negative value moves the 
position toward the beginning of the collection. 

Skip moves the scan position deltaPos bytes forward or backward 
within the collection, it transfers no data. 

NOTES: 

1. A scanner is used to access the various types of collections. 

2. The ToolKlt-deflned collection types are files, strings, lists, and arrays. 

There Is a subclass of TScamer for scanning each of those classes. See 
TFileScanner, TStrlngScarmer, TArrayScanner, and TUstScanner for more 
information. 

3. In general, before you can use a scanner to access a collection, you must 

create a collection object of the right type. See TArray, TUst TFile, and 
TString for more inf ormation 

4. CONCEPTUAL methods are not Implemented, or even defined in the 

interface. They are here as models only; every subclass can define its 
interface to these methods In its own way. 
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CLASS: TScrollBar 

SUPERCLASS: TObject 

DEFINED SUBCLASSES: none 
INHERITED DATA FIELDS: none 
DATA FEUDS: R flrstBoc TScroller; 



R iSVislWe: BOOLEAN; 

None that are Important for applications. 



The first scroller for this scroll 
bar. Other scrollers are found 
through a field of this scroller. 
TRUE if this scroll bar should be 
drawn. 



METHODS: 
NOTES: 

1. applications never subclass or otherwise deal directly with this class. 
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CLASS: TScioller 

SUPERCLASS: TObJect 

DEFINED SUBCLASSES: none 
INHERITED DATA FIELDS: none 
DATA FIELDS: R scrolIBan TScroUBar; 



R 
R 



band: TBantb 

SBoXID: TSBOXID; 



The scroll bar that contains this 

v scroller. 

" Trie band affected by this scroller. 
The scroll bar library 
representation of the entire scroll 
bar. If there is more than one 
scroller in the scroll bar containing 
this scroller, the ToolKit finds the 
others through this field 

METHODS: None that are important for applications. 

NOTES: 

1. applications nev e r subclass or otherwise deal directly with this class, 

2. This call defines and controls the mechanisms that scroll bands. 
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none 



••"CLASS: TSelectton 
SUPERCLASS: TObJect 

DEFINED SUBCLASSES: none 

INHERITED DAT A FIELDS: 

DATA FIELDS: R Window: TWindOW; 

R panel: TPaneb 

R view: TVIew; 

RW kind: INTEGER; 

RW anchoiLPt LPoint; 
RW cunLPt LPoint* 



R boundLRect: LRect 
RW coselectlon: TSelectlon; 



canCrossPanels: BOOLE/W; 



METHODS YOUR APPUCATION WILL CALL: 



The window object in which the 

selection was made. 

The panel object in which the 

selection was made. 

The view object of panel object in 

which the selection was made. 

The kind of selection. means no 

selected object (nothingKirxft The 

rest of the codes are defined by 

the view object 

The place the mouse went down 

(view-relative). 

The place the mouse was last 

tracked. 

The bounding box of the selction. 

If this selection does not implement 

certain commands, the ToolKit 

sends the commands on to 

coSelectloa unless coselectlon is 

NIL. 

TRUE if the selection can be in 
two panels, used for cross-panel 
dragging. 



CREATE (object' TObJect; heap: THeap; itsVlew: TView; itsKind: INTEGER; 
ItsAnchorLPt: LPolnft TSelectton; 

heap is the heap used for this document. 

ItsVlew references the view that displays the selected object. 

ItsKind is the type of the selection. Indicates there is no selected 

object. Other values are defined by the applicatioa 

ltsAncnorLPolnt is the mouse-down point Used solely by the 

applicatioa 

TSelectioaCREATE creates an object of type TSelectlon 

CantDolf 

TSelectioaCantDoit is called by other routines when a command 
cannot be done. A warning message from the phrase file is 
displayed 



11-119 



Lisa TcclKft Reference Manual Part II Class Reference Sheets 

FreedAndReplaceoBy (selection: TSelection> ^Selection; 

selection is the new selection (usually a CREATE method call to 
^Selection or some descendant of TSelectioa) 
The return value is the new selection. 

TSelectionPreedAndReplacedBy replaces the old selection object with 
a new selectioa Keeping the same handle for the new selection as 
the old one had. You should always use this method when changing 
selections. This makes certain that handles in your application that 
pointed to the old selection to point to the new selectioa 

METHOOS YOUR APPLICATION OFTEN OVERRIDES: 

Newcommand (cmdNumben TCmdNumber): TCommand; DEFAULT; 

cmdNumter indicates the menu command chosen. 
The return value is a c omman d object, or NIL. 

TSelecUonJsiewCommand calls window.NewCommand if there is no 
coSelection. You must write your own selecUoaNewComrnand 
method in order to do selection-specific command processing. If you 
do so, construct trie Newcommand procedure around a CASE 
statement with a case for each of your commands. End it with 
OTHERWISE New Co nYriand^TSelecUonJs>ewQ]n¥Twnd. Return NIL or 
a new command object NIL means the document was not changed 
signf icantly. In that case, Newcommand must carry out the action of 
the command itself. Return an instance of TCommand when the 
command cannot be undone, in that case, first call 
window.CommitLast to Commit the last command object then carry 
out the action of the command, and then return an instance of 
TCommand. In all other cases, return NO. or an instance of a 
descendant of TCommand. The descendant of TCommand has 
methods that perform the action of the command. See the ToolKit 
Segments for more information. 

Highlight (Mcffrranslt: TKgnTransit); DEFAULT; 

MghTransit is the change in highlighting of the displayed object The 
choices are: hNone, hOffToOim, hOffToOn, hDimToOn, hDimToOf f, 
hOnToOff, and hOnToOim. Dim highlighting is normally used when 
the window is inactive. 

Higftiicjit changes the appearance of an object when it is selected 
and deselected, and when the window is activated or deactivated. 
Your Hkptiight method should not try to keep track of the state of 
highlighting. The ToolKit always calls this method with the proper 
rtghtransit value. Highlighting is normally done using XOR. Call 
SetPenToHighli^rt(hic^TTanslt) and then FrameLRect PaintLRect or 
some other appropriate drawing routine. 
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MouseMove (mouseLPt: LPolnft DEFAULT; 

mouseLPt is the view-relative point where the pointer is located. 

You may write a MouseMove routine that takes some 
application-dependent action, such as drawing something, when the 
mouse button is still down. TSelectioaMouseMove does nothing. 

MouseRelease; DEFAULT; 

You may write a MouseRelease routine that takes some 
application-dependent action, such as creating a command object, 
when the mouse button is released. TSelectioaMouseRelease does 
nothing. 

METHODS YOUR /APPLICATION MIGHT OVERRIDE: 

MousePress (mouseLPt: LPoint); DEFAULT; 

mouseLPt is the view-relative point where the pointer was located 
when mouse was pressed. 

You may write a MousePress routine that takes some 
application-dependent action when the mouse is pressed. 
TSelectioaMousePress does nothing. 

INTERNAL METHODS: 

DoKey (ascik CHfiR; keycap: BYTE; shiftKey, appleKey, optionKey: 
BOOLEAN); 

ascii is the character typed at the keyboard. 

keycap defines the actual key pressed on the keyboard. See the 

hwint documentation in the Internals document. 

sftiftkey tells whether or not the shift key was pressed along with the 

character. 

appleKey tells whether or not the Apple key was pressed along with 

the character. 

optionKey tells whether or not the option key was pressed along with 

the character. 

TSelectioaDoKey determines what action is to be taken when a key 
is pressed. If appleKey is TRUE, the key combination is checked to 
see if it is one of the menu commands. If so, windowXX)Command is 
called Otherwise, the method checks if there is a selected object 
If not, process-Stop is called and a warning message is displayed. If 
there is a selected object, seiectionDoKey checks which editing or 
character key was pressed. Depending on the key, one of the key 
methods listed under the following section, INTERNA. NO-OP 
METHODS, is invoked When the ToolKit is used without those 
overridden (often by a building block), all produce an alert to the 
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user. All of these routines are implemented in one or several 
txiilding blocks. You can implement these routines yourself, if you 
wish. You would probably override DoKey if you were writing a 
terminal emulator. 

INTERNAL NO-OP METHODS: 

All of these routines are implemented (or will be implemented) in a 
number of building blocks. In particular* the Text Building Block 
implements these in a way appropriate for text You can override any of 
these routines. 

KeyBacKfWonfc BOOLEAN); DEFAULT; 

KeyChai(crt CHAR); DEFAULT; 

KeyClear; DEFAULT; 

KeyEntei(dh, dv. INTEGER); DEFAULT; 

KeyForwantfWortt BOOLEAN); DEFAULT; 

KeyPause; DEFAULT; 

KeyRetunv DEFAULT; 

KeyTab(fBackwant BOOLE/*flt DEFAULT; 

SelectecParagraphs; DEFAULT; 

This group of methods handle keyboard entry. They are usually 
called by the ToolKit 

OTHER METHOO& 

Clone (heap: THeap> TObject; 

heap is the document heap. 

TSelectioaClone creates a copy of the Deselection, as well as of the 
selection. You can override this method. 

GetHysteresis (VAR hysteiPt: Paint); DEFAULT; 

hysteiPt is the current hysteresis, expressed with a vertical 
(hysteiPLv) and horizontal (hysteiPUfl component 

GetHysteresis gets the current mouse hysteresis. You can override 
this method. 

HaveVlew (view. TView); 

view is the view in which the selection is seen. 

This method is called to change the view pointed to by the selection. 
Do not call this method. You might want to call TPaneLHaveView, 
however. 
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MarkChanged; DEFAULT; 

MaxKChanged marks the document as having been changed. 

OanDoOomrnand (cmdNumben TCrndNumber; V^* checklt: BOOLEAN): 
BOOLEAN; DEFAULT; 

cmdNumber is the reference number for an application or ToolKit 

command. 

checklt tells whether or not the correspoding menu item should have 

a checkmark next to it 

The return value indicates whether or not the command can be done. 

CanDoComman d reports whether the command referred to by 
cmoMumber can be done. You often need to override this method. 
When you do so, if the command is not one of your application's 
commands, call CanDoCtJHiiianQ>SElJ^window.Car^ See 

the ToolKit segments for a more complete description. 

IcfleBegin (centiSeconds: LONGINT); OEFAULT; 

centiSeconds the amount of time, in hundredths of a second, since 
idle time started 

TSelectionJdleBegin calls coSelectloaldleBegia if there is a 
coSelectioa or TWindowJdleBegia if there is not TWindowJdleBegin 
lets other processes run. You may want to override this method to 
do idle time tasks that are very time critical. 

IdleContinue (centiSeconds: LONGINTfc DEFAULT; 

centiSeconds the amount of time, in hundredths of a second, since 
idle time started. 

TSelectiorUdleContinue calls coSelectioaloleOonUnue, if there is a 
coSelectioa or wlndowJdleOontinue, if there is not 
TWindowJdleOonUnue calls process.TtackCursor, if the process is 
active. If this process is not active, TWindowJdIeContinue lets other 
processes run. You may want to override this method to do idle time 
tasks that should be repeated and can be put of f until this time. 

IdleEnd (centiSeconds: LONGaNTlt DEFAULT; 

centiSeconds the amount of time, in hundredths of a second, since 
idle time started. 

TSelectiorUdleEnd calls coSeiectiorUdleEna if there is a coSelectioa 
or windowJdleEna if there is not TWindowJdleEnd does nothing. 
You may want ot override this method to stop processing of your idle 
time tasks. 
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Deselect; DEFAULT; 

TSelectioTLDeselect turns off highlighting of the selection and replace 
it with noSeiectioa 

MoveBackToAnchor; DEFAULT; 

MoveBackToAnchor is called by the ToolKit when a cross-panel drag 
is attempted, and it is not successful for some reason. In that case, 
MoveBackToAnchor should restore the selected object to its position 
before the drag attempt was begun. If you want that to happen, you 
must implement this method. TSelectionJ^loveBackToAnchor does 
nothing. 

Restore; DEFAULT; 

Restore replaces the current selection with the last selection saved 
with selectioaSave, which is normally the selection before the last 
command. You may want to override this method. 

Save; DEFAULT; 

Save stores the current selection so that it can be restored if the 
user requests an undo of the last command. You may want to 
override this method. 

Reveal (asMuchAsPossible: BOOLEAN); DEFAULT; 

asMuchAsPossible indicates whether or not the selection should be 
shown to the greatest extent possible. 

Reveal controls the displaying of the selection. If asMuchAsPossible 
is TRUE, the panel is scrolled whenever the user does anything that 
affects the selection so that the largest part of the selected objects 
are displayed as can be shown. If asMuchAsPossible is FALSE, the 
display is not changed to show more of the selection. 

DrawGhost; 

DrawQhost can be Implemented to draw an xORed ghost image 
during cross panel dragging. It is called by the ToolKit, between 
each call to MousePress and the first call to MouseMove. If you 
imlement this method, you should also Implement MouseMove so that 
it moves the ghost image. TSelectioaMouseMove does nothing. 

FAILURE CONDITIONS: none 



NOTES: 



1. This class is usually subclassed for use. However, when no object is 
selected, the null selection object can be an instance of TSelectlon itself 
with the kind field set to nothingKind. 

2. The descendant of TSelectlon usually contains a handle on the selected 
object, or a list of handles on the selected objects. 
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3. The selected object is one of the objects displayed by the view object 
associated with the panel object containing this selection. Commands 
often apply only to a selected object. There can be many selected objects 
in each panel or no selected objects. Each panel object, however, always 
has a selection (an Instance of "reelection or a descendant of "reelection), 
even when there are no selected objects. 

4. Successive selection objects in a particular panel object use the same 
object handle. Use the method setectionFreedAntReplacecSy to free the 
old selection and give its handle to the new selection 

5. If there is more than one selection the one in the active window's 
selectPanel is active and receives commands. 

6. If there is a selected object in the selectPanel it is always highlighted in 
some way, while selections in other panels may or may not be highlighted 

7. coSelection is used when you want to take advantage of a building block 
other other pre-defined unit's action on most edit key events, while 
implementing different action on some edit key events. 

8. To use the coSelection feature, create your own descendant of "reelection 
and put the building block's selection in the coSelection field of your 
application's selection object The ToolKit's default edit key routines, 
which are inherited by your descendant of TSelection all check to see if 
there is a coSelection and, if there is one, send the key event to the 
coSelection. 

9. For the key events that you want handled differently from the way the 
building block handles them, reimplement that edit key routine in your 
descendant of TSelection. Since your routine presumably would not check 
for a coSelection the coSelection is ignored. You can always send some 
keys to the coSelection and handle others yourself. 

ia Successive coSelections of a particular selection object may use the same 
object handle. Use FreedAndReplaoedBy to change coSelections. See note 
4. 

11. See the ToolKlt Segments for examples and more details of use of 
selections. 
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CLASS: TStiing 

SUPERCLASS: 



TCollectlon 



DEFINED SUBCLASSES: none 

INHERITED DAT A FIELDS: Size: LONGINT; 



dynstart: INTEGER; 
hOleStart: INTEGER; 

holeSlze: INTEGER; 

hOleSt<* INTEGER; 



DATA FIELDS: 



none 



The number of real elements In 
this list, not counting the hole. 
This is a LONGINT for the 
benefit of huge collections, such 
as remote data bases. It is 
always in the INTEGER range 
for instances of TString. 
The number of bytes from the class 
pointer to the dynamic data area 
means hole at the beginning; 
value of size means hole at the 
end. 

The initial size of the hole, 
measured in the number of 
members that can fit in the hole. 
How much to grow the collection 
by if the holeSlze goes to a 



METHODS: 



CREATE (object TObJect; itsheap: THeap; lnttialSlacfc INTEGER* 
TString; 

inltialSlack is the size of the Initial hole, in member-sized units, 

TString.CREATE creates an empty string on itsHeap. inltialSlack 
is a hole for string members. Because the string is created with 
a hole, the insert methods can be used to initialize the list 
without allocating any space. 

At 0: LONGINT* CHAR; DEFAULT; 

i is an ordinal position in the string. 

The return value is the character at the given position. 

At returns the character at the given position in the string. 

DelAil; 

DelAll deletes all the characters of a string. The string itself is 
not deleted. 
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DelAt (k LONGINT}; DEFAULT; 

1 is an ordinal position in the string. 

DelAt deletes the character at position f characters after i are 
then moved to fill in the empty space. 

DelFlrst; 

DeFirst deletes the character at, the beginning of the string. 
DelLast; 

DelLast deletes the character at the end of the string. 

DelManyAt fl, howMany: LONGINT}; 

1 Is an ordinal position in the string. 

howMany indicates the number of string characters to be deleted. 

DelManyAt deletes a number of characters from the string. The 
first deleted character is at position L 

Draw Q: LONGINT; howMany: INTEGER* 

1 is an ordinal position in the string. 

howMany indicates the number of string characters to be drawn. 

Draw calls QuickDraw to write the given part of the string at the 
current pen position. 

Each PROCEDURE DoToCharacter(characten CHAR)fc 

DoTcObJect is PROCEDURE that takes a character as its 
argument. 

Each applies the given PROCEDURE to each character in the 
string. 

First: CHAR; 

The return value is a character. 

First returns the first character in the string. 

InsAt (b LONGINT; characten CHAR* 

1 is an ordinal position in the string, 
character is a character. 

InsAt inserts an character in the string. The newly inserted 
character occupies position L 

InsFirst (characten CHAR* 

character is a character. 

InsFirst inserts an character at the beginning of the string. The 

newly inserted character occupies the first position in the string. 



H-127 



Lisa ToolKlt Reference Manual Part 11 Class Reference Sheets 

InsPStrAt (k LONGINT; pStn TPStringfc 

i is an ordinal position in the string. 
pStr is a pointer to a string. 

InsPStrAt inserts a string into this string at position L 

InsLast (character: CHAR); 

character is a character. 

InsLast inserts an character at the end of the string. The newly 
inserted character occupies the last position in the string. 

Last- CHAR; 

The return value is a character. 

Last returns the character at the end of the string. 

ManyAt (i, howMany: LONGINT> TString; 

i is an ordinal position in the string. 
howMany is a numDer of characters. 

ManyAt returns a string with the characters from the original 
string beginning at position 1 and continuing through howMany 
characters. 

MemberBytes: INTEGER; OVERRIDE; 

MemberBytes returns the size of a member of the string, which is 
always 1. (Tnis method is more useful for other types of 
collections,) 

Pos (after: LONGINT; character: CHAR): LONGINT; 

after is the index number of a character in the string, 
character is a character. 

Pos finds the positions of the first instance of character after 
position after. 

PutAt (b LONGINT; ctBracten CHAR); 

i is an ordinal position in the string, 
character is a character. 

PutAt deletes the character at position I and replaces it with 
character. 
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Scanner: TStrlngScanner; 

The return value is a stringScanner for this string. 

Scanner returns an object of class TStrlngScanner, allowing use of 
stringScanner methods. This is equivalent to 

string^cannerFrorn (l, scanForward); 

ScamerFrom (flrstToScart LONQINT; seanDirectlort TScanDirection> 
TStrlngScanner; DEFAULT; 

flrstToScan is a position in the string. 
scanDlrectlon scanForward or scanBackward. 
The return value is a new stringScanner. 

ScarmerFrom returns an object of class TStrlngScanner, with 
stringScannerPosltion equal to flrstToScan minus one (or plus one, 
if scanDirectlon is scanBackward!), so that the first call to 
$trlngScamer.Scan returns the character at flrstToScan 

StartEdit (withSlack: Ir4TEGHRl; 

withSlack is the new value for holeStd. 

StartEcttt changes the value of holeStd to withSlack, so the next edit 
call creates a hole of size withSlack, so that subsequent edit calls 
act more quickly. 

StopECflt; 

StopEolt removes the hole from the array and sets holeStd to (zero). 
Any subsequent edit call removes any hole it forms, 

ToPStr (pstn TPStringk 

pstr is a pointer to a string 

ToPStr transfers this string into the string at pstr. 

ToPStrAt ft, howMany. LONGDMT; pstr: TPStringfc 

i is an ordinal position in the string. 
howMany is a number of characters. 
pstr is a pointer to a string. 

ToPStrAt transfers part of this string into the string at pstr. 

Width (k LONQINT; howMany: INTEGER); 

1 is an ordinal position in the string. 
howMany is a number of characters. 

Width calls the QuickDraw routine, TextWidth. 
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FAILURE CONDITIONS: Heap can't grow. 

Array > 32K bytes. 



NOTES: 



Deleting from empty string. 
Subscript out of range. 



1. A string Is a space-optimized list of characters, similar to an array, except 

that TArray requires even membeiBytes, and TString has a memberByte 
value of 1. 

2. strings have three modes: create mode, edit mode, and static mods 

3. When you first create a string, it is in create mode. You define an 
initlalSlack value in the CREATE call. The string is given enough empty 
space to hold InitlalSlack characters. That space is the hole. As you add 
characters, the space in the hole is used for the new characters. The 
amount of space allocated to the string does not change until you fill up 
the hole with characters. You can also call stringStopEdit which removes 
the hole from the string. 

4. When the hole is filled, the string enters static mode. In static mode, no 
hole is ever maintained. If you add a characters, the string is copied into 
a space large enough to hold the additional characters. If you delete a 
character, the extra space is freed. 

5. Enter edit mode by calling string£tartEdlt(withSlack). In edit mode, a hole 
big enough for wlthSlack characters is initially created. As you add 
characters, the size of the hole decreases. When the hole is entirely 
filled, the space allocated to the string is increased so there is a new 
hole big enough for wlthSlack characters. If you delete characters, the 
extra space is added to the hole. Call stringiStopEdlt to stop editing. 
Any space taken up by the hole is then freed. 
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CLASS: TStrlngScamer 

SUPERCLASS: TScamer 



DEFINED SUBCLASS: 
INHERITED DATA FIELDS: 



TFlleScanner 

R collection: TCollection; 
R position: LONGINT; 



R increment: INTEGER; 



scanDone: BOOLEAN; 



R atEndt BOOLEAN; 



DATA FIELDS: R actual: LONGINT; 



The suing being scanned. 
The current position of 
the scanner- The scanner 
position is always 
between, before, or after 
members: 0-before first, 
size^l-after last 
The change in position 
for every scare 1 if 
scanning forward, -1 if 
scanning backward. 
When this is TRUE, the 
next Scan call returns 
FALSE, signalling the end. 
of the scan. The VAR 
parameter of the Scan 
method, which normally 
contains the next object 
in the string, is 
unchanged after the Scan 
call. 

TRUE if the end of the 
list is eminent, so that 
the next Scan call will 
return F^-SE. 

The number of bytes transferred 
In the last transfer operation. 



METHODS: 



CREATE (object: TObject; ItsStrlng: TString; itstaitialPosition: 

LONGONT; ItsScanDirectiort TScanDirection> TStringScamer; 

itslnitialPosition is the Initial ordinal position in the string. 
ItsScanDirectlon is scanForward or scanBackward. 

TStrlngScannerX3REATE creates an object of type TStringscarmer, 
which is used to access ItsStrlng. itsStrlng must exist before a 
stringscarmer can be created for it; however, you can use a 
T5tring.CREATE call in your TStrlngScanner.CREATE call, which 
will create the necessary string object 
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Append (character. CHAR); DEFAULT; 

character is a new member of the string. 

Append adds character to the string Immediately after the current 
position position is adjusted by adding 1, so that the next Scan 
returns the character after the new character. 

Delete; DEFAULT; 

Delete deletes the character at the current position position is 
adjusted by subtracting L 

DeleteRest; DEFAULT; 

Delete deletes all characters after the current position position 
is unchanged. The next call to stringscanner^can returns FALSE. 

Done; DEFAULT; 

Done signals that you are finished using this stringScamer. The 
next call to stringScanner.Scan returns FALSE, as if the end of 
the string had been reached. Unlike when the end of the string is 
reached, however, the returned character in Scan remains 
unchanged. 

Free; OVERRIDE; 

Free deallocates this stringScarmer object 
Obtain: CHAR; DEFAULT; 

The return value is a character from the string. 

Obtain returns the current character. 

ReadArray (heap: THeap; bytesPerRecord: IN7EGER> TArray; 

heap is a heap on which to allocate a new TArray. 

bytesPerRecord is the number of bytes per record in the desired 

TArray. 

The return value is an array containing data from the string. 

readArray first reads a 2-byte count of the records in the array 
and then transfers that number of records times bytesPerRecord 
bytes from the string into the array that it allocates. 

ReadNumber (numBytes: SizeOfNumber): LONGINT; 

numBytes is between 1 and 4. 

The return value is a LONGBNT read from the current position in 

the string. 

ReadNumber reads a number of length numBytes. If numBytes is 
even, the number is signed. stringScamerPosition is increased by 
numBytes. The number is not read as ASCII. 
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ReadObJect (heap: THeap> TObject; 

heap is a heap. 

The return value Is a new object 

ReadObJect reads the next four bytes from the string and takes 
that as a class pointer. It then creates a new object on heap 
using that class pointer. 

Replace (character: CHAR); DEFAULT; 

character is a character that replaces the current character. 

Replace removes the current character from the string and 
replaces it with the given character. The new character is now 
the current character. 

Scan (VAR nextChar. CHAR): BOOLEAN; DEFAULT; 

nextChar is the next character from the string. 

The return value is F^_SE if the end of the string has been 

reached or stiingScanner Done has been called. 

Scan begins at the beginning of the string and, each time it is 
called, returns the next character. The returned character is 
referred to as the current character. The value of Scan is TRUE 
until Scan is called after the last character in the string is 
reached, or until strlngScannerXtone has been called. If the end 
of the string was reached, and Done was not called, the value of 
nextChar is NIL. If Done was called, nextChar keeps the last 
value it had. When method Done is called or when the scanner 
reaches the end of the string, the scanner is freed. 

Seek (strin^os: LONGINT); 

strlngpos is the location to which you wish the scanner to move. 
stringPos - is the beginning of the string. 

Seek moves the current scan position to stringPos, it transfers no 
data. 

Skip (deltaPOS: LONQDMTk 

deltaPos is the number of bytes you wish the scan position to 
move within the string. A positive value moves the position 
toward the end of the string; a negative value moves the position 
toward the beginning of the string. 

Skip moves the scan position deltaPos bytes forward or backward 
within the string. It transfers no data 
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WriteArray (a TArray); 

a is the TArray you wish copied into the string. 

WriteArray copies a into the string, preceded by a 2-byte count 
of the number of records, 

WriteNumber (value: LONGINT; numBytes: SizeOfNumber); 

value is the number you want wrjttea 

numBytes is the number of bytes you want the number to occupy 

in the string (l to 4). 

WriteNumber writes value into numBytes bytes of the string, 
dropping high-order bits if numBytes < 4. 

WriteObject (heap: THeap> TObject; 

heap is a heap. 

The return value is an object 

WriteObject is the inverse of ReadObJect 

XfeiContiguous (whichWay. xReadWrite; collection: TCoilection); 

whichWay is either >«ead, xwrite, or xSklp. 
collection is the TCoilection you are reading or writing. 

XferContiguous reads or writes collection; when whichWay - 
xRead. it resizes collection and appends the contents of the string 
to the end of collection. 

XferFleids (whichWay: xReadWrite; object: TObject); 

whichWay is either xRead, xwrite or XSkip. 

object is the object from which you are reading or to which you 

are writing. 

XferFleids reads or writes the contents of the fields of object 
The class pointer is not read or written. 

XferRandom (whichWay: rtteadWrite; pFirst: Ptr; numBytes: LONGINT; 
mode: TIOMode; offset: LONGINT); DEFAULT; 

whichWay is either xRead, xwrite or xSkip. 

pFirst points at the first byte to read data into or write data out 

of. It is ignored with xSkipi 

numBytes is the number of bytes read, written or skipped. 

mode is mAbsolute, mRelative or mSequentlal 

offset is a byte position from the beginning of the string when 

mode is mAbsolute, or from the current string position if 

mRelative. 

XferRandom reads, writes or skips numBytes bytes of the string, 
starting at the indicated position. Ail the other I/O methods call 
this method. XferRandom calls the Lisa OS directly. Reading 
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and writing are always done left to right (from the beginning 
towards the end) regardless of the scanDirectioa 

XferSequential (whichWay: xReadWrite; pFlisU Ptr; numBytes: 
INTEGER^ (DEFAULT; 

whichWay is either xReafl, xWrlte or xskip. 

pFiist points at the first byte to read data into or write data out 

of. It is ignored when whichWay^ equals xSkip. 

numBytes is the number of bytes read written or skipped 

XferSequential reads,, writes or skips the next numBytes bytes of 
the string. Reading and writing are always done left to right 
(from the beginning towards the end) regardless of the 
scanDirectioa 

XfeiPString (whichWay: xReadWrite; pSte TPStringfc 

whichWay is either xRead xWrite or xSkip. 
pStr is a pointer to a string to read or write. 

XfferStrihg reads a string pStr* from a string or writes it to a 
string. If whichWay is xRead the destination string must be long 
enough. The amount transferred depends on the length of pstr\ 



NOTES: 



1. A stringScarmer is used to access a stored data string, to scan it, and to 
manipulate its individual elements. Use TUstScamer and its subclasses to 
scan lists. 

2. Before you can use a stringScamer to access a string, the string must be 
opened by T3tringScanner.CREATE. stringScannerPree closes the string. 

3. The Actual variable contains the number of bytes of data most recently 
transferred to or from the string, it is the same as the number requested 
unless error > a 

a. The Xfer methods are preferred, because the same procedure may then be 
able to transfer data to or from a string. 

5. You may have more than one stringScamer open on the same string at the 
same time. 

6. WARNING: No checking is done that sufficient space has been allotted for 
data reads at pFIrst* or pstr\ 
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•""•CLASS: TVlew 
SUPERCLASS: 
DEFINED SUBCLASSES: 

INHERITED DATA FIELDS: 



Tlmage 

TPaginatecMew 
TPagevlew 



extentLRect: LRect; The size of the entire 

view. 



view: TVlew; 



Always contains SELF. 



allowMouseOutside: BOOLEAN; 

FALSE by default When 
FALSE, and the mouse 
point is outside the vlew / 
the point is converted to 
the closest point within 
the view. If TRUE, the 
point is not converted, 
in that case, mouse 
points can be outside 
extentLRect and, 
particularly, can be 
negative. This feature 
exists primarily for use 
with sidebands. Note 
that your program must 
be prepared to handle 
mousepoints outside 
extentLRect 



DATA FIELDS: 



R 
R 

R 
R 



panel: TPanel; 
cllckLPt LPoint; 



printManager: TPrtntManager; 
res: Point; 



R fltPagesPerfecUy: BOOLEAN; 



R IsPrintdble: BOOLEAN; 



The panel that looks on this view. 

The last place the user clicked the 

mouse button. 

The printManager for this view. 

The resolution of this view, in 

terms of spots per inch. A spot is 

the smallest unit that can be 

displayed, equivalent to a pixel. 

The resolution has two dimensions: 

a vertical (res.v) and a horizontal 

(re&n) resolution. 

Whether or not the TooiKit should 

alter the view size automatically so 

that there is always a whole 

number of pages. 

Whether or not this view can be 

printed. 
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R IsMainVlew: BOOLE^fc Whether or not this is a main view. 

If FALSE, this is an auxiliary view 
such as a page view or paginated 
view. 

R stdScroil: LPolnt; The standard amount of scrolling 

from one click on the scroll arrow. 
There is a standard scroll value for 
two dimensions: a vertical 
(stdSerolLv) and a horizontal 
(stdScrolLh) scroll distance. 
RW scrollPastEnct Point; How much the ToolKit should scroll 

past the end of the view. 

METHOD YOUR A>PPUCAT10N MUST OVERRIDE: 

CREATE (object TObJect; heap: THeap; itsPaneL- TPanel; itsExtent LRect; 
ItsPrlntManager. TPrlntManager; ItsDfltMargins: LRect; 
ItsFitPagesPerfectlyfiOOLEAN; ItsRes: Point; IsMainVlew: 
BOOLEAN* TVlew; 

ItsPanel is the panel looking on this view. 

ItsExtent is the size of the view. 

ItsPrlntManager is the prlntManager to be used for printing this view, 

or NIL, if this view cannot be printed. 

ItsDfltMargins is a rectangle which specifies, in view coordinates, the 

page margins used when printing. 

itsFltPagesPerffectly indicates whether or not the ToolKit should 

format the view so that when it is printed, it occupies a whole 

number of pages. 

itsRes Is the resolution of this view, in dots per inch. 

IsMainVlew Is TRUE If this Is the primary representation of the data, 

and not a paglnatedVlew or a pageVlew. 

TView.CREATE creates an object of type TVlew. Normally, your 
application does not call this method directly; instead, you call 
paneLNewVlew or paneLNewStatusVlew. Those methods call CREATE. 

Draw; 

You should Implement a Draw method in each descendant of TVlew to 
draw the part of the view visible in the pane or on the page. Your 
Draw method should assume that thePad is set up to draw in one 
pane. (See TPad in Chapter 3 for an explanation of thePad.) 

METHODS YOUR /WJCATION OFTEN O^RRIDES: 

MousePiess (mouseLPt: LPolnt); 

mouseLPt is the view-relative point where the pointer was located 
when the mouse button was pressed. 

You normally write a MousePiess routine in each descendant of 
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TVlew that takes some application-dependent action when the mouse 
4s pressed. TView-MousePress calls TSelectlooMousePress. 

EachActualPart (PROCEDURE DoToObJect (obj: TObJectfc 

PROCEDURE DoToObJect is any procedure that takes a TObject 
object-reference variable as an argument DoToObJect cannot be a 
method. 

EachActualPart is Intended to apply DoToObJect to each object in the 
view's set of objects. If you store your application's objects in the 
window, you should implement wlndowJEachActualPart rather than 
view£ach/\ctualPart TMew£achActualPart actually calls 
TWindow£achActualPart which returns an error message indicating 
that EachActualPart was not implemented. 

METHODS YOUR APPLICATION MIGHT OVERRIDE: 

MouseMove (mouseLPt: LPointJt 

mouseLPt is the window-relative point where the pointer is located. 

TVievJMouseMove calls TSelectloaMouseMove. You may write a 
routine that takes some application-dependent action when the mouse 
button is still down. More often, your MousePress method creates a 
selection that handles the mouse move itself. View.MouseMove is 
always called at least once before view.MouseRelease is called. 

MouseReiease; 

TView.MouseRelease calls TSelectiooMouseReleasa You may write a 
routine that takes some application-dependent action when the mouse 
button is released. More often, your MousePress method creates a 
selection that handles the mouse release itself. When the mouse 
button is released, the ToolKit calls vtew-MouseMove one last time 
with the final pointer position, and then calls view.MouseReleasa 

OkToDrawin QRectlhView: LReet): BOOLEAN; 

lRectlnvlew is a view-relative rectangle. 

TVlew.OkToDrawIn always returns F/4.SE. You may reimplement it 
to improve the performance of your applicatioa It is called when 
the application or a building block wants to draw or erase from 
command or mouse code. PaneUnvalLRect is normally called to 
cause the ToolKit to tell the view to draw the next time 
window.update is called If, for speed you want the application or 
building block to draw directly, you must call paneLOkToDrawln to 
ask for permissioa The panel object may deny permission if page 
breaks are in the way, or may call the vlew.OkToDrawln method to 
ask the view object for permissioa If the application is certain that 
only one object's image is in IRectlnView (as opposed to several 
layered images), it can return TRUE. Note that it is permissible to 
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draw in the view using XOR, as is sometimes done in Hkjtticja 
•methods, without asking permission. 

SetMlrtVlewSize (VAR mlnLRect: IRect); 

minLRect is the minimum view size acceptable to the application. 

SetMinVlewSize is called by the TooiKit to obtain the minimum view 
size. It returns the views current extentLRect by default You can 
reimplement this method if you want to return some other value. 
The actual size of the view set by the TooiKit can be larger than the 
value given by SetMinVlewSize, depending on the value of 
view.fltPagesPerfectly. 

OTHER METHODS: 

AddStripOfPages (vhs: VHSelect); DEFAULT; 

vhs tells whether a vertical or horizontal strip is to be added. 

AddStripOfPages increases the view size by one vertical or horizontal 
strip of pages. 

BelnPanel (panel: TPanel); 

panel is one of the application's panels. 

BelnPanel installs this view in the given paneL 

CtorsorAt (mouseLPt: LPolnt): TCursoiNumber; DEFAULT; 

mouseLPt is the view-relative point where the pointer is located. 
The return value is the type of cursor to be set, or noCursor. 

CursorAt returns the position of the mouse pointer. The return value 
indicates the kind of cursor that is to be displayed. If you do not 
care, you can set the value to noCursor. In that case, the TooiKit 
displays the default cursor, usually the arrow cursor. Applications 
often override this method. 

DoReceive (selection: "reelection; lPUrtView: LPolntJc BOOLEAN; 

selection is the selection object that points to objects that the user 
is dragging. 

lPUrMew is the point where the objects were left by the user. 
The return value is whether or not this operation can be done. 

DoReceive is used to implement cross-panel dragging. 
TViewjDoReceive always returns F^-SE. If you want to implement 
cross-panel dragging, your view should pick up the selection and do 
something appropriate with it, and return TRUE if the operation is 
successful. Applications might override this method. 
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ForceBreakAt (vhs: VHSelect; prececfln^ocatlort LONGINT; 
proposedLocaUort LONGINT* LONGINT; 

vhs indicates either or vertical or a horizontal page break. 
pieceding-ocaUon is the location of the preceding page break. 
proposedLocation is the proposed page break locatioa 
The return value is where the page break is actually placed. 

The ToolKit calls ForceBreakAt t>efpre setting each page break. You 
can override the default implementation to examine the location of 
the page break and decide where you want the break to actually be. 
Return that value. The return value must be greater than 
precedlngj-ocatlon and less than or equal to proposedLocation. 

QetStdScroll (VAR deltaLStd: LPoint); 

deltaLStd is the preset standard scroll. deltaLStd.v is the vertical 
scroll; deltaLSt&h is the horizontal scroll. Both are expressed in 
dots, which are the units of the view's resolution. 

QetStdScroll finds out the standard scroll values. The values indicate 
the distance scrolled for each click on a scroll arrow. 

MaxPageToPrtnt: LONGINT; 

The return value is a page number. 

MaxPageToPrtnt returns the last page that will print when this view 
is printed. By default that page number is derived by multiplying 
the number of columns of pages times the number of rows of pages. 
You can override this method if you want so that some of the 
highest-numbered pages are not printed. For example, you might 
want to do that if your application is a spreadsheet and only the 
first few cells have data in them. 

NoSelectiort TSelection; 

The return value is a null selection. 

TVlewJsloSelection returns a null selection for use when the view has 
no selected object You can override this routine so that it returns a 
selection object of your own selection class. 

RedoBreaks; DEFfiULJ; 

RedoBreaks orders the ToolKit to recalculate page breaks. You can 
override this method, if you wish. 
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RemapManualBreaks {FUNCTION NewBreakLocation(vhs: VHSeiect; 

OldBreak: LONGINT> LONGINT); 

NewBreakLocation is a function that calculates new page breaks. 
vhs indicates whether the page breaks are vertical or horzontal. 
oldBreak is the old page break location. 

RemapManualBreaks changes the locations of all page breaks. You 
never override it, but you might call It Call this method if the 
locations of manual page breaks in 'your view are dependent on 
printer metrics. If that is the case, when printer metrics change, you 
need to recompute the locations of the manual breaks. Call 
RemapManualBreaks from your viewiteactToPrinterChange method. 
To do so, you must first create a FUNCTION that takes the old 
manual break location and returns the corresponding new location. 

When TMew-RemapManualBreaks is called, it first clears all 
automatic page breaks. RemapManualBreaks then hands your 
NewBreakLocation function each manual page break, one at a time. 
RemapManualBreaks replaces each old manual page break with the, 
corresponding new page break returned by NewBreakLocation. 
Finally, after all the manual page breaks have been processed, 
RemapManualBreaks calls RedoBreaks, which recomputes the 
automatic page breaks. 

Resize (newExtenU LRect); DEFAULT; 

newExtent is the new view size. 

Resize sets the size of the view to the indicated new size, and 
removes any superfluous page breaks. 

SetFunctionValue (keyword: S255; VfiR itsValue: S255)t 

keyword is the name of a variable whose value you want 
itsValue is the value of the variable. 

SetFunctionValue finds the value of the given variable, and returns it 
as a text string. TVlew^etFunctionValue works only for pAGE} and 
fTTTUEj. If you want to use this to get the values of other variables, 
you must re-implement it 

FAILURE CONDITIONS: none 

NOTES: 

1. You normally subclass Tvlew and then use the subclass to create the 
application's view, or one of the application's views. The subclass often 
contains data fields for the information being viewed. For example, if the 
information displayed in a view Is stored as a list of objects, then the 
subclass of Tvlew adds one field of class TUst As another example, the 
window object could contain fields referencing document objects, and the 
view could access them through the view.paneLwlndow field. 
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2. Usually only a portion of the view is displayed on the screen at any one 
time. - 

3. The parts of the view that are displayed are displayed by pane and 
bodyPad objects. 

4. Every panel contains one or more panes, each of which may display a 
different portion of the view object 

5. A window may contain a number of panels, each of which looks on a 
different view object 

6. Invalidated screen areas are updated between events, and when the 
application requests. Also, automatic scrolling may occur while the mouse 
button is down, depending on the position of the mouse pointer. 
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**"CLAS& TWindow 

SUPERCLASS: 



TArea 



DEFINED SUBCLASS: TDialOp£ox 

INHERITED DATA FIELDS: R lmerRect: Rect; 



Contains the size of the window, 
excluding the entire frame. 
Contains the size of the window, 
including the frame. 
parentBrancrc TBranchArea; 

Not used in TWindow. 



R outerRect: Rect; 



DATA FIELDS: R panels: TUst {OF TPanelJ; 



panelTree: TArea; 



R dlalocpox TDlalogBox; 

R selectPaneh TPanel; 
R undoSelPanel: TPanel; 

clickPaneL* TPanel; 

undoCllckPaneL- TPanel; 

R selectwlndow: TWindow; 

undoSelwlndow: TWindow; 
wmgrlD: TWlndowlD 
R IsReslzaWe: BOOLEAN; 



The panels in the window. There is 
always at least one. See class 
TPaneL 

When the window contains no 
panels (when it is first created) 
contains NIL. When the window 
contains one panel, contains the 
panel When the window contains 
more than one panel, contains a 
TBranchArea that points to the 

References the dlalocpox for this 

window. NO. if SELF is a dialog 

box window, or if there is no dialog 

box for this window. 

The panel with the active selection. 

The selectPanel during the last 

command. 

The panel where the mouse button 

was last clicked. 

The cllckPanel during the last 

command. 

The window with the active 

selection Either SELF or its 

dlaloojBox 

The window with the active 

selection during the last command. 

ORD of the pointer to the Window 

Manager's grafPort 

Tells whether or not there is a 

Resize Box 
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believewmgn BOOLEAN; 



maxlnnerSize: Point; 
changes: LONGaNT; 
lastcmd: TCommancfc 
printerMetrics: TPrinterMetrics; 
pgSzOK: BOOLEAN; 

p^gOK: BOOLEAN; 
panelToPrlnt TPanel; 



objectToFree: TObject; 



METHOD YOUR APPLICATION MUST OVERRIDE: 



If TRUE, the Toolkit should believe 
the window manager's idea of the 
size of the window; this is FALSE 
(for example) when the application 
creates the window object before 
the window is put on the screen. 
The window size the user explicitly 
set by using the grow icon. 
Shows the number of changes since 
the last save. 

The last command object that can 
be undone. 

Properties of the printer. 
Whether to allow user-defined 
page-sizes in Format For Printer 
dialog. 

Whether page-range dialog should 
be enabled in the dialog that 
appears in response to the Print- 
menu command. This is normally 
TRUE 

The panel to print when the user 
asks for printing. Note: if there is 
more than one printable panel in 
the window,, choice should be made 
by providing separate menu items. 

This field is used to hold a 
reference to an object that should 
be freed at end of the event loop. 



BlankStadonery; DEFAULT; 

BlankStationery creates a panel a view, and an initial selection, it is 
called when the user tears off a piece of stationery. The application 
is completely responsible for implementing this method. See the 
TooiKit Segments for a complete discussion of this method. 

CREATE (object: TObject; itsHeap: THeap; ItsWmgrlD: TWIndowlD; 
itsReslzabfflty: BOOLEAisQe TWlndow; 

ItsHeap is the heap used for this document 

ItsWmgrlD is the internal identification number for the window 

manager. 

itsResizability tells whether or not the window should have a size 

control box. 

TWlndow-CREATE creates an object of type TWlndow. You need to 
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implement CREATE so that it creates a window of your application's 
-subclass of TWindow. See the ToolKlt Segments for a complete 
discussion of this method. 

METHOD YOUR APPLICATION WILL CALL: 

CREATE (object: TObJect; ItsHeep: THeap; itswmgrtD: TWindowID; 
itsReslzability: BOOLEAN): TWindow; 

itsWmgrlD is the internal identification number for the window 

manager. 

itsResizability tells whether or not the window should have a size 

control box 

TWlndow.CREATE creates an object of type TWindow. 

METHODS YOUR APPLICATION MIGHT CALL: 

CommitLast; DEFAULT; 

Commits the last com m an d object, and sets windowJastCmd to ML. 

ChildWithPt (pt Point; childList: TUsfcVAR nearestPt Point* TAiea; 

pt is a point in window-relative coordinates. 
childList is a list of areas contained within this window. 
nearestPt is the point in the returned area closest to pt 
The return value is one of the areas from childList. 

ChildWithPt first finds the point In windowJnnerRect closest to pL 
It then the compares the new point to the outerRects of all the areas 
in childList When it finds the area that contains the point it finds 
the point in that area's innerRect that is closest to the point That 
value is returned as nearestPt The area containing nearestPt is the 
return value. 

Docommand (cmdNumben TOmdNuntjeft DEFAULT; 

TWlndowJDoCornmand handles command dispatch. If you override this 
method for some reason, you should end your routine by calling 
TWinctow-DoCommand. In general, however, you should override 
TWindowJstewCommend rather than this method. You might call this 
method if there is an action that acts like a menu command, such as 
a button in the main window. 

EachActualPart (PROCEDURE DoToOb ject (fllteredObi TObJectJt 

See below. 
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EachVirtualPart (PROCEDURE DoToObJect (filteredObJ: TObjectJfc 

PROCEDURE DoToObJect is any procedure that takes a TObJect 
object-reference variable as an argument DoToObJect cannot be a 
method 

TWiridow£achVlrtualPart calls TWindow-FllterDispatch which checks 
the last command and if comman d Poing - TRUE, calls 
command£achVirtualPart to apply DoToObJect to each object in the 
window's set of objects. If cartnantiDolng - FALSE, 
TWindow£achVirtualPart calls lrnage£achActualPart If you store 
your application's objects in the view, you should call 
view£achVlrtualPart rather than window£achVirtualPart 

ResizeTo (newSize: Point); 

point is the new lower right comer of the lmerRect 

ResizeTo changes the size of windowJnnerRecL It performs 
higher-level operations on the window, such as resizing areas 
contained within this window, and then calls SELF-REsize. 

ToggleRag (VAR flag: BOOLEAN); DEFAULT; 

flag is any boolean variable. 

ToggleFlag switches the value of flag, from TRUE to F^-SE, or from 

FfiUSE to TRUE. 

Update (doHilite: BOOLEAN); DEFAULT; 

doHttlite tells whether or not selections should be highlighted 

TWindow.Mpdate updates the display within the window to fill in 
newly uncovered areas or areas changed by the application. Only 
invalidated areas are redrawn. The ToolKit calls this after every 
event, which includs cxarimands, keystrokes, and calls on MousePress, 
MouseMove, and MouseRelease. See note 4. 

METHX) YOUR APPUCATION MIGHT OVERRIDE: 

EachActualPart (PROCEDURE DoToObJect (filteredObJ: TObjectJfc 

PROCEDURE DoToObJect is any procedure that takes a TObJect 
object-reference variable as an argument 

EachActualPart is intended to apply DoToObJect to each object in the 
window's set of objects. If you store your application's objects in the 
view, you should Implement view£achActualPart rather than 
window£achActualPart TWindow£achActualPart actually returns an 
error message Indicating that EachActualPart was not implemented 
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The following methods are listed In groups according to function. 

WINDOW ATTRIBUTES METHODS: 

GetTltle (VAR title: S255k DEFAULT; 

title Is the string in the window's title bar. 
GetTltle obtains the string in the window's title bar. 

fcActive: BOOLEAN; DEFAULT; 

The return value indicates whether or not the window is action. 

IsActive returns TRUE if this window is presently the active window. 

Setwmgrld atswmgrtdt TWIndowID]t DEFAULT; 

itsWmgrtd is a window manager ID. 

Setwmgrld sets the ID for this window. It also sets the port fields 
of the panes In this window. Your application should not call this 
method. 

MOUSE BUTTON METHODS: 

DownEventAt OrcusePt: Point); DEFAULT; 

mousePt is the point where the mouse button was last pressed. 

DownEventAt is called when the mouse button is pressed. This 
method computes double and triple mouse clicks. It also calls 
wlndowDownAL 

DownAt (mousePt- Point): BOOLEAN} 

mousePt is the point where the mouse button was last pressed. 

DownAt figures out where the mouse was located when the button 
was pressed by checking the resize box and calling paneLDownAt 
until it finds the right panel. 

DIALOG BOX HANDLING METHODS: 

PutupcftalogBox (dlaiogBox: TDtaiogBoxJ; default; 

dlaiogpox is a fflatogBox-reference. 

PutUpDialocpox displays the given dialog box. 
TakeDownDialocpox; DEFAULT; 

TakeDownDialo^ox removes the displayed dialog box 
DISPLAY HANDLING METHODS: 
Focus; 

Focus focuses the grafPort on the window. 
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Frame; 

Frame draws the frame of the window, including the grow box TTie 
title bar is drawn by the window manager; the scroll bars are drawn 
by TPaneLFrama 

Highlight frtiojhTransit: THg^Transit); DEFAULT; 

highTransit is the change in highlighting of the displayed object The 
choices are: hNone, hOffToDlm, WOffToOa hDlmToba hDimToOff, 
hOnToOff, and hOnTcOira 

Wcjtilcjit changes the state of highlighting within the window. 
TWlndowXicyilicpt calls paneU-ttoJilicjit for every panel in the 
window. 

Refresh (r Actions: TActions; highTransit: THicpYTransit); 

rActions is one of the set (rErase, iFrame, sBackgrounoy iDraw). 
highTransit is the change in highlighting of the displayed object The 
choices are: hNone, hOffToDlm, hOffToOa hDlmToba hDimToOff, 
hOnToOf t and hOnTcOira 

Refresh refreshes the window's display. It calls paneLRefresh for 
each panel in the window. 

RESIZING METHODS: 

DownlnSizeBox (mousePt: PointJ; DEFAULT; 

mousePt is the point where the mouse button was pressed 

DownlnSizeBoxP is called by the ToolKit when the user presses the 
mouse button is the resize box. 

Resize (moving: BOOLEAN DEFAULT; 

moving indicates whether the window is being moved (TRUE) or 
resized (FALSE). 

Resize resets size from portRect size (with adjustments). 

ResizeTo (newSize: Point); DEFAULT; 

newSize sets the new lower right comer of the window. 

ResizeTo changes the size of the window. Your application can call 
this method. 
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COMMAND AND MENUS METVCOS: 

CanDoCommand (cmdNumben TCmtNumber; VAR checklt: BOOLEAN): 
BOOLE/Ysfc DEFAULT; 

cmdNumber Is the reference number for an application command. 
checklt tells whether or not a check mark should appear next to the 
command in the menu 

CanDoCommand tells whether or»not the command can be done at 

this time. You can override this method to handle your commands; 
call SUPERSELFXianDoCommand in your method. 

CanDoStdCommand (cmdNumben TCmdMumber; VAR checklt: BOOLEAN): 
BOOLEAN; DEFAULT; 

cmdNumber is the reference number for a standard command. 
checklt tells whether or not a check mark should appear next to the 
command in the menu. 

CanDoStdCommand tells whether or not the command can be done at 
this time. You should not need to override this method. 

CommitLast; DEFAULT; 

CommitLast commits the last command. 
LoadMenuBar; DEFAULT; 

LoadMenuBar inserts the application's menus into the menu bar. 
MenuEventAt (mousePt: Point); DEFAULT; 

mousePt is the point where the mouse button was pressed. 

MenuEventAt gives the point where the mouse button was last 
pressed when the pointer was in a menu You should not call or 
override this method. 

NewCommand (cmdNumben TCmdNumbeft TCommand; DEFAULT; 

cmdNumber Indicates the menu command chosen. 
The return value is a TCommand object, or NIL. 

you must write your own wlndowJMewCommand method in order to 
process commands that apply to the entire window. If you do so, 
construct the NewCommand procedure around a CASE statement with 
a case for each of the commands you implement End it with 
OTHERWISE newConrwnand^TWlndowistewCornmar^ Return NIL or a 
new TCommand object NIL means the document was not changed 
signficantly. In that case. NewCommand must carry out the action of 
the command itself. Return an instance of TCommand when the 
command cannot be undone. In that case, first call 
window.CommitLast to Commit the last comman d object then cany 
out the action of the command and then return an instance of 
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TOommand. In all other cases / return an instance of a descendant of 
TCommandL The descendant of TCommand has methods that perform 
the action of the command. 

NewStdCommand (cmdNumben TCmdNumter> TCommand; 

cmdNumber is the reference number for a standard command. 
The return value is a command object. 

NewStdCommand returns a command object for the given standard 
command. This method is used for standard commands that affect 
the entire window. You should not need to override this method. 

Pexformcommand (newCommand: TCommand); 

newCommand is a command object 

PerfoimCommand performs the given command. It first calls 
lastCmdCommit and then calls SELF-SaveCommand. Finally, it calls 
SELFPerformLast 

PerfoimLast (cmdPhase: TCmdPhase); 

cmdPhase is either doPhase, undoPhase, or redoPhasa 

PerfoimLast calls Perform for the last command. The first time the 
command is performed, the cmdPhase is doPhasa After that, 
undoPhase and redoPhase alternate. 

SaveC&mmand (newCo m mand: TCommand); 

newCommand is a command object. 

SaveComma nd saves the given command as lastco m man d . When 
referring to the command after using this method use 
windowJastCmd instead of newComman d . 

SetupMenus; 

SetUpMenus is called when the user clicks in the menu bar or types 
an apple key combination. The method initiates the process of 
checking If the command can be done. In general, you do not 
override this method. Instead, implement CanDoCommand for each of 
you descendants of TSelectioa 

UhdoLast; 

UhdoLast calls windowJastCmdPerform if wlndowiastCrndPerffcrm 
was last called with cmdPhase-doPhase or redoPhase, 
window JastCmdPerform is now called with crndPhase-undoPhase. If 
windowJastCrndPerform was last called with crndPhase-undoPhase, 
windowiastCmdLPerform is now called with cmdPhase-redoPhasa 
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WantMenu (menuIO. INTEGER; irClipboant BOOLEAN* BOOLEAN; 

menuID is a menu ID number. 

InClipdoard tells whether or not the clipboard is the active document 
The return value indicates whether or not this menu should be 
displayed in the menu bar. 

WantMenu is called by the ToolKit each time the menu bar is 
displayed, which happens whenever the window is activated. 
LoadMenu calls WantMenu once for each menu in the phrase file with 
numbers from 1-89 in non-debug versions of the ToolKit, and with 
numbers from 1-99 for debug versions of the ToolKit When 
inCliptooard is TRUE, however, this is only called for menu 1000, 
WantMenu always returns TRUE by default You can override it so 
that it returns FfiLSE for certain menus. 

SELECTIONS DURING COMMANDS METHODS: 

RestoreSelection; 

RestoreSelection is called when undoing a command. 

RevealSelection (asMuchAsPossible, doHUlte: BOOLEAN); 

asMuchAsPosslble tells whether or not the document should be 
scrolled to reveal as much as possible of the selection. 
doHilite tells whether or not the selection should be highlighted if it 
is displayed. This value is passed on to update, 

RevealSelection determines how the selection is displayed when a 
command is given. 

SaveSelection; 

Saveselectlon saves the current selection in all panels. This is the 
reverse of RestoreSelection, 

DESKTOP METHODS: 

Activate; 

TWlndow-Activate activates the window. This method assumes that 
the grafPort is focused on this window. Be very careful if you 
override this method. 

Deactivate; 

TWindow-Deactivate deactivates the window. Tftls method assumes 
that the grafPort is focused on this window. Be very careful if you 
override this method. 
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StashPlcture (WghTransit: THg^Transit); 

hio^Translt is the change in highlighting of the displayed object Trie 
standard choices are: hNone, hOffToDira hOffToOa hDimToOa 
hDimToOff, hOnToOff , and hOnToDim. 

StashPicture saves a QuickDraw picture of the window when the 
window in inactive* 

CURSOR METHODS: 

CursorFeedback: TCursorNumber; 

The return value is the current cursor type number. 

CursorFeedback returns the cursor type number for the cursor that is 
currently displayed. Do not override this method; you can override 
Tvlew.CursorAt instead. TVlew-CursorAt gets called as a result of 
this method. 

PickStdCursor; 

PickStdCursor displays the standard arrow cursor. Do not override' 
this method; you can override TView.CursorAt instead. 

PRINTING METHODS: 

AcceptNewPrintirtglnfo (document: TDocManager; prReserve: TPrReserve); 

document the docManager for the affected document. 
prReserve holds the printer informatioa 

This method is called when the printer formatting information 
changes. 

ChkPrMlsmatch; 

This method checks to see if the printer information has changed, and 
if it is valid. 

QetPrinterMetrtcs; 

This method finds out the characteristics of the printer for which 
this document is formatted. 

Print (panel: TPanel; nixPoJfange: BOOLEAN; nixWholeDiaiog: BOOLEAN*; 

panel is a panel in the window. 

nbPgRange Indicates whether or not all pages should be printed. If 

TRUE, the user is not given a dialog ta choose a page range for 

printing. 

nlxWholeDialog. if TRUE, suppresses the entire dialog with the user. 

Print prints the contents of the view displayed in the given panel 

FAILURE CONDITIONS: none 
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NOTES: 

1. TWindow is always subclassed for use. 

2. The methods of TWindow create and manage the window seen on the 
display. The default window object provides resizing, and activation and 
deactivation capabilities. 

3. To use TWindow, subclass it and define your own wlndowBlankStationery 
routine. Other functions, except for application commands, are taken care 
of automatically. 

4. When an area of the screen is changed, either by a window resize or 
scroll, or by a command, that area is Invalidated using paneUnvalLRect or 
thePadJnvalLRect Wlndow.update is automatically called in the 
processJRun control loop. All invalidated areas are then redrawn. (You 
can call Draw methods directly to redraw the display, but first you must 
seek permission from paneLOkToDrawIa) If you want the program to 
redraw the display before returning to the control loop, which is rarely 
necessary, call wlndow.Update after invalidating the regions to be redrawn. 
The easiest way to invalidate an area is with paneUnvalLRect 
thePadJnvalLRect must be called through paneLOnAUPadsDo. 
paneUnvalLRect does that for you 
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